Aege-041-engsub Convert03-08-26 Min Apr 2026

| Code | Body | Meaning | |------|------|---------| | 400 | "error":"Unsupported file type", "file":"foo.xyz" | Invalid format. | | 422 | "error":"Trim window out of bounds", "detail":"End time exceeds file duration" | Validation. | | 500 | "error":"Conversion failed", "detail":"Parser threw at line 842" | Server side. | 8. Backend Implementation Details | Component | Tech Stack | Key Libraries | |-----------|------------|---------------| | API Gateway | Node.js (Express) or Go (Gin) | multer (multipart), jsonwebtoken | | Conversion Service | Python 3.11 (FastAPI) – stateless | pysrt , ass , webvtt-py , ttml , python‑srt , ffmpeg‑python (only for timestamp arithmetic) | | Storage | AWS S3 (temporary bucket) with lifecycle rule 30 min. | | Queue (optional for large files) | Amazon SQS / RabbitMQ | Workers pull jobs, update progress via WebSocket. | | WebSocket (progress) | Socket.io (if using Node) or FastAPI‑WebSocket | Broadcast requestId updates. | | Auth | Centralised JWT (OAuth2) | Middleware validates sub claim. | | Testing | PyTest (backend), Jest (frontend) | Coverage ≥ 90 %. | Conversion Algorithm (pseudo‑Python) def convert_subtitle(source_bytes, src_fmt, tgt_fmt, trim_start: Optional[timedelta] = None, trim_end: Optional[timedelta] = None) -> bytes: # 1️⃣ Parse source parser = PARSERS[src_fmt] subs = parser.from_bytes(source_bytes)

# 2️⃣ Trim (if requested) if trim_start is not None or trim_end is not None: start = trim_start or timedelta(0) end = trim_end or subs[-1].end subs = [s for s in subs if s.start >= start and s.end <= end] AEGE-041-engsub convert03-08-26 Min

# 2b Adjust timestamps so they start at 0 or at the original start offset = start for s in subs: s.start -= offset s.end -= offset | Code | Body | Meaning | |------|------|---------|

The intent of this ticket is to give users a quick, reliable way to while optionally trimming the conversion to a specific time window (03 min 08 sec – 26 min 00 sec) . | | WebSocket (progress) | Socket

#

--- After conversion ---------------------------------------------------- | File: my_video.srt → my_video.vtt (converted) | | Progress: ████████▏ 78% | | Preview (first 5 cues): | | 1 00:03:10,000 --> 00:03:14,000 Hello world! | | 2 00:03:15,000 --> 00:03:18,000 … | | … | | [ Download ] [ Download All (zip) ] | +---------------------------------------------------------------------+ All controls are keyboard‑focusable. Validation messages appear inline under the relevant fields. 7.1 Endpoint POST /api/v1/subtitle/convert Content-Type: multipart/form-data Authorization: Bearer <jwt> Request (multipart) | Part | Type | Required | Description | |------|------|----------|-------------| | files | file | ✔︎ | One or more subtitle files. | | targetFormat | string | ✔︎ | srt , vtt , ass , ttml . | | trimStart | string (HH:MM:SS) | ✖︎ | If supplied, start of time window. | | trimEnd | string (HH:MM:SS) | ✖︎ | If supplied, end of time window. | Response (JSON) – on success "requestId": "c9f0e5b4-7d12-4a5b-9f2e-8c2d1e9a6b34", "files": [ "originalName": "my_video.srt", "convertedName": "my_video.vtt", "downloadUrl": "/api/v1/subtitle/download/c9f0e5b4-.../my_video.vtt", "preview": [ "index":1,"start":"00:03:10,000","end":"00:03:14,000","text":"Hello world!", "index":2,"start":"00:03:15,000","end":"00:03:18,000","text":"…" ] ], "zipDownloadUrl": "/api/v1/subtitle/download/c9f0e5b4-.../all.zip"