TermSub v2.1.0: UI Polish, 59 Languages & Editable Timecodes

What's New

🌍 Expanded Language Support — 59 Languages

TermSub now supports 59 source and target languages, covering the full OpenAI Audio API (Whisper / GPT-4o transcribe) supported language set.

• Searchable language dropdown — type to find any language by English or native name (e.g., "Español" or "Spanish")
• Pinned common languages — the 10 most spoken languages plus Persian (Farsi) appear at the top for one-click access
• Native-name display — each language shown as English — English, Arabic — العربية, Persian (Farsi) — فارسی
• New centralized app/core/languages.py module replaces hardcoded dictionaries across the codebase

⏱️ Editable Timecodes in Subtitle Timeline

Subtitle segments can now have their timestamps edited directly in the web UI.

• PUT /segments/{segment_id} accepts start_time and end_time fields
• Chronological validation ensures start_time is strictly before end_time
• Smart session handling prevents DB refresh from undoing edits on commit
• Unified timestamp formatting utilities (format_timestamp, format_timestamp_vtt) across all export formats

🎵 Audio Chunking for Large Files

Audio files that exceed OpenAI Whisper's 25 MB upload limit are now automatically split and transcribed seamlessly.

• app/core/audio.py — new 196-line stateless audio utility module
• chunk_audio_if_needed() — intelligently splits audio at ~10-minute intervals (well under the 25 MB threshold)
• Fast FFmpeg stream-copy splitting — no re-encoding, chunks are produced in seconds
• Seamless timestamp merging — chunk results are shifted by cumulative offsets to produce a single continuous segment list relative to the original audio
• Per-chunk progress logging — each chunk reports its progress via the existing WebSocket pipeline

---

UI Improvements

Feature	Description
Searchable language dropdown	Tom Select integration replaces native <select> with type-ahead search across all 59 languages
Dark mode for dropdowns	Complete CSS overrides for Tom Select in dark theme — no more blinding light dropdowns
"How to Use" modal	Built-in onboarding guide accessible from the UI — walkthrough of upload → transcribe → review → export
Version indicator	New GET /api/version endpoint + footer badge showing the running app version
Toast notifications	Non-blocking toast messages for user feedback (success, error, info)
Enhanced timeline cards	Editable timestamps with contenteditable, improved Add/Split/Remove buttons with hover states
Activity log refinements	Cleaner message formatting, consistent progress reporting across all pipeline stages

---

Export Pipeline Improvements

• Fixed DB session lifecycle in all export endpoints (SRT, VTT, TXT, JSON) — content is now generated while the session is still open, preventing lazy-loading errors
• Sanitized export filenames — derived from the original video filename for consistency
• Unified timestamp formatting — format_timestamp() and format_timestamp_vtt() used consistently across SRT and WebVTT exporters

---

Bug Fixes

• MIT license copyright year corrected from 2025 → 2026
• Leading silence preserved — first subtitle timestamp now correctly respects leading silence in the audio
• Import sorting fixed in test files for consistent style
• OpenAI 429 retry logic — longer exponential backoff for rate-limited batches so they wait and retry instead of being dropped

---

Testing

• New tests/test_audio_chunking.py — 186 lines of comprehensive tests covering:
  • Chunking decision logic (under/over size threshold)
  • Offset accumulation across multiple chunks
  • FFmpeg integration test (skipped if FFmpeg not installed)
  • Full chunked transcription orchestration with cleanup verification

---

Migration Notes

No database migrations required for this release. The changes are fully backward-compatible with existing v2.0.0 installations.

Docker Deployment

docker compose pull
docker compose up --build

Local Development

git pull origin main
source venv/bin/activate
pip install -r requirements.txt
# Restart Celery worker and FastAPI server

TermSub is a production-ready FastAPI application for AI-powered video transcription, translation, and terminology management — with particular strength for Persian (Farsi) and RTL languages.

v2.0.0: Production Architecture — PostgreSQL, Celery & Strict Typing

This release graduates TermSub from a single-file prototype to a production-ready, horizontally-scalable architecture.

🏗️ Architecture Overhaul

PostgreSQL replaces SQLite

• Full concurrent access support for multi-worker deployments
• Proper connection pooling and transaction safety
• Production-grade backup and replication ready

Celery + Redis Distributed Task Queue

• Background jobs are now handled by Celery workers instead of a single-threaded local queue
• Redis Pub/Sub for real-time WebSocket broadcasts from distributed workers
• Heartbeat monitoring, timeout recovery, and retry logic at the Celery level

Modern SQLAlchemy 2.0

• Migrated to Mapped[] / mapped_column() type-safe ORM declarations
• Proper session lifecycle management with get_db_session() context managers

🔧 Code Quality

Strict Static Typing

• Full MyPy strict = true compliance across the codebase
• Replaced legacy Optional[X] and List[X] with modern X | None and list[X] syntax
• Explicit return type annotations on all functions

Linting & Formatting Pipeline

• Added Ruff for fast linting, import sorting, and code formatting
• Added MyPy for static type checking
• GitHub Actions CI runs both on every push to main

🗄️ Database & Migrations

• New migration: add_celery_task_id_column.py for Celery task tracking
• Enhanced schema validation on startup with clear error messages for outdated databases

📊 Stats

37 files changed, +3,142 / −2,584 lines

v1.6.1: OpenAI Cloud Migration — Streamlined Architecture & Bug Fixes

This release completes TermSub's migration from Google Gemini to OpenAI cloud-native transcription and translation. The architecture is now simpler, faster, and removes the local WhisperX alignment dependency entirely.

🚀 Major Changes

OpenAI Cloud-Native Pipeline

• Transcription now uses OpenAI whisper-1 instead of Gemini Flash + WhisperX alignment. Segment-level timestamps are born directly from the cloud — no secondary local alignment step required.
• Translation now routes through OpenAI models instead of Gemini.
• Audio pipeline switched from WAV to MP3 for faster uploads and lower bandwidth.

Architecture Refactor

• Extracted the built-in UI into a dedicated frontend/ directory for cleaner separation of concerns.
• Introduced a dedicated app/agents/ module with a standalone Translator Agent.
• Major cleanup of app/main.py — reduced complexity by ~1,800 lines.

🐛 Bug Fixes

• Fixed audio extraction edge cases for certain video codecs.
• Resolved file size limit handling on large uploads.

📁 Files Changed
19 files, +3,013 / −3,703 lines

Release v1.5.1: UI Polish, Local Sync Engine & Documentation

✨ New Features & Experience Enhancements

Drag-and-Drop Media Uploads: The video upload zone now supports direct drag-and-drop for .mp4 and .srt files (complete with visual hover states) alongside the standard click-to-browse system.

Server Portability (No .env required): The FastAPI backend no longer requires a hardcoded system variable to boot up. The application now degrades gracefully and relies exclusively on the session API key provided through the UI, preventing crash-loops on fresh installations.

📝 Documentation

VideoTranslationPro User Guide: Added a comprehensive user_guide.md to walk users through the new UI features, timeline controls, and local pipeline setup.

🐛 UI Bug Fixes & Adjustments

Target-Language Subtitle Splitting: Fixed a critical bug in the Subtitle Timeline UI where clicking "Split" on a segment would incorrectly fetch and split the source transcription text rather than the translated text.

Dark Mode Contrast Fix: Resolved a styling issue in the Glossary / Extracted Terms table where typing a preferred "Standard" translation resulted in invisible black-on-black text during dark mode.

Glossary Streamlining: Surgically removed the redundant "Frequency" column from the extracted terms UI to maintain a cleaner, more focused layout.

⚙️ Engine & Pipeline Improvements

Word-Count Indexing for Alignment: Replaced the brittle string-matching algorithm with a strict, mathematical word-count slice method. This ensures WhisperX phonetic data maps cleanly back to the LLM segments without freezing on spelling variations or numerals (e.g., "100" vs "hundert").

Timestamp Safety Clamping: Added duration limiters to start and end timestamps sent to the alignment model. This prevents fatal crashes when initial segment guesses mathematically exceed the actual audio file duration.

Fail-Hard Dependency Tracking: The pipeline now actively checks for required ML libraries (torch, torchaudio, whisperx) and halts with a clear error if they are missing, rather than silently failing and causing subtitle drift.

v1.5.0-beta: The Lean Editor Update – Gemini Pipeline, Interactive Timelines & Dark Mode

Welcome to TermSub v1.5.0-beta! 🚀

This major beta release marks a massive pivot in TermSub's architecture. We have aggressively streamlined the backend by ripping out heavy local inference engines to create a lightning-fast, 100% cloud-native Gemini pipeline. Paired with a brand-new interactive timeline editor and cinematic dark mode, this update transforms TermSub from a developer prototype into a sleek, professional web application.

With over 1,400 lines of legacy code removed, the app is leaner, faster, and ready for public testing.

🔥 Major Highlights

1. The Interactive Subtitle Editor

We’ve overhauled the timeline to give you total manual control over your subtitles, strictly enforcing broadcast industry standards (max 42 characters per line, max 2 lines per card).

• Split, Add, & Remove: Every subtitle card now features interactive action buttons. You can easily split long sentences perfectly in half at the click of a button, insert blank cards to adjust timing, or delete segments—with the backend automatically shifting the database sequence to keep everything perfectly aligned.

2. Lightning-Fast "Gemini-Only" Pipeline & Auto-Cleanup

• Zero Local Bottlenecks: We completely removed the heavy faster-whisper local models. Transcription and translation are now routed exclusively through Google Gemini Flash for maximum speed, with WhisperX retaining its role for precise word-level timestamp alignment.
• Self-Cleaning Storage: To save server space, the background worker now automatically and permanently deletes uploaded video files and temporary .wav extracts the moment a job is completed or hits a fatal error.

3. Smart Routing: The "Skip Terminology" Fast-Track

Don't need a glossary for a simple video? You can now bypass the terminology extraction phase entirely!

• A new Skip Terminology toggle allows you to route videos directly from transcription straight to translation, cutting processing time in half.
• Full-Transcript Context: To ensure the Translation Agent doesn't lose the plot, we now gather the entire video transcript and inject it into the LLM's prompt as critical background context before it translates a single line, vastly improving narrative consistency and tone.

4. Cinematic Dark Mode

TermSub now features a professional, eye-strain-reducing Light/Dark theme toggle. The new UI uses a sleek slate and charcoal palette (#121214) accented with neon cyan, persisting your preferences seamlessly via localStorage.

---

⚠️ Important Upgrade Notice

If you are upgrading from v1.4.0, your database requires a schema update to support the new routing logic. You must run the following migration before starting the application:

python migrations/add_skip_glossary_column.py



Note for Testers: This beta focuses on a streamlined single-track experience (source → target). Multi-language database tracks have been temporarily simplified to ensure maximum speed and stability for this editor rollout.

v1.4.0 - Multi-Language Tracks & Resilient AI Pipeline Upgrades

Changelog

TermSub v1.4.0 introduces powerful multi-track language capabilities, allowing you to generate, store, and seamlessly toggle between multiple localized subtitle variants within a single video project workspace. This release also marks a major architectural milestone in pipeline hardening—introducing script-aware data mergers and defensive parsing loops to insulate the application against downstream LLM variations.

🚀 New Features & UI/UX Upgrades

• Multi-Language Subtitle Tracks: Added the ability to run multiple translation passes sequentially without wiping out previous language runs.
• Dynamic Timeline Track Toolbar: Injected a low-profile language track manager toolbar right above the subtitle timeline cards (#trackSelector) to let users swap display text instantaneously on screen without page refreshes.
• Interactive "+ Translate Another Language" Panel: Added an inline target-switch module that bypasses initial audio transcription to directly run the Translation Agent on your existing project timeline.
• Expanded Global Language Catalog: Replaced hardcoded layouts with a global, sorted dictionary of 20+ major global languages natively supported by Gemini 3 Flash, populating both the project configuration and the track-editor dropdown boxes.
• Strict Target Validation Guards: Enforced high-visibility input warning highlights (border-red-500) and function-arresting execution guards to block empty translation execution states.

🔧 Bug Fixes & Architecture Hardening

• Resolved Language-Code Drift (Critical): Fixed a tracking bug where auto-detected transcript segments written to the database under "original" caused translation queries to trigger dangerous global-table fallbacks. Segments are now accurately aligned with their specific language code strings at write time.
• Script-Aware Overlap Merger: Upgraded the sliding-window compilation algorithm to evaluate target alphabet strings. This prevents Latin-based fallback scripts from accidentally overwriting localized target scripts (like Persian or German) during overlapping window merges.
• Glossary Language Disconnect Fix: Ported the script-aware overlap guard to context_analysis_service.py to stop late-stage terminology extraction passes from bleeding English back into localized glossary grids.
• Asynchronous View-State Lock: Patched the frontend view router (updateButtonVisibility) to prevent WebSocket translation messages from force-snapping users back to the terms panel if they are working on a secondary language track.

🛡️ Defensive AI Parsing & System Stability

• Bulletproof JSON Stripper Helper: Added a robust utility function utilizing regex pattern matching to safely extract content nested inside raw { ... } brackets, discarding conversational introductory fragments or markdown wrappers (json ... ) returned by the model.
• Un-Crashable Analysis Fallback: Wrapped context evaluation parsing inside a graceful try...except loop. If an LLM payload fails structural compliance checks, the background engine drops a warning log and generates safe, standard fallback definitions instead of letting the task queue hang in an unrecoverable ERROR state.

📦 Database & Migrations

• Schema Upgrade: Created tracking schema migration (migrations/add_segment_language_code.py) to append an indexed language_code string column straight to the segments table.
• Safe Duplicate Handling: Configured background tasks to cleanly execute targeted deletion passes for any matching video_id + target_language rows right before inserting bulk translation updates, protecting database constraints against data bloat.

---

Deployment Dependencies: Run source venv/bin/activate and ensure database migrations are verified before initiating your local Uvicorn development server instance.

v1.3.0: The Interactive Subtitle Workstation Update

🚀 Overview

Version 1.3.0 completely transforms the application from a linear, forward-only generation script into an interactive, non-linear Subtitle Workstation. Users can now review, proofread, and batch-edit their translations directly inside the browser canvas before exporting perfectly aligned subtitle files.

---

💎 Key Features

⏱️ Interactive Subtitle Review Timeline

• Visual Workspace: Added a beautifully styled, scrollable timeline view in the right-hand panel that populates instantly upon pipeline completion.
• Frame-Accurate Alignment: Fixed critical positional parameter issues within the background worker to ensure WhisperX forced-alignment syncs acoustic phonemes flawlessly, yielding millisecond-accurate timecodes.

✍️ Inline Card Editing & Auto-Save

• WYSIWYG Word Processing: Turned static text blocks into live editing fields using HTML5 contenteditable.
• Zero-Interruption Sync: Implemented an asynchronous background saving pipeline (PATCH /videos/{id}/segments/{sid}). Modifying a word and clicking away seamlessly updates the local SQLite database without locking up the user interface.
• Safe-Fail Guards: Introduced an empty-string discard filter. If a line is accidentally wiped out, the UI safely restores the original text block to prevent timeline data corruption.

🔍 Global Find & Replace Console

• Batch Terminology Correction: Added a sleek, high-efficiency utility bar at the top of the timeline panel to sweep and replace systemic AI translation errors across the entire video file in milliseconds.
• Race Condition Prevention: Built a global execution lock state that blocks duplicate double-clicks and gracefully manages concurrent processing between manual card saves and batch text overrides.

---

🎨 UI/UX Refinements

• Decluttered Workspace: Stripped away the legacy, pre-translation "Custom Terms" override grid to streamline the desktop layout.
• Progressive Disclosure: The project setup panel (languages, engine keys) now automatically collapses when processing starts to leave a clean, focused log and terminal view.
• Intelligent Toast Notifications: Eliminated noisy pipeline spam and reintroduced targeted, high-layer (z-[9999]) visual confirmation popups specifically for user editing actions.
• Persistent History Logs: Step durations and pipeline timestamps now remain perfectly intact inside the activity monitor across pipeline phase transitions.
• Air-Tight Hydration: Fixed state restoration on browser page reloads. Refreshing a completed project now immediately hydrates the full timeline grid and context brief perfectly from the URL state.

---

🛠️ Under the Hood

• Optimized SQL performance utilizing SQLAlchemy's selectinload() strategy to eagerly package segment payloads in a single database round-trip.
• Added soft-degradation fallbacks to the transcription service, cleanly routing critical external environment or package exceptions into handled user logs without freezing the job queue.

TermSub v1.2.0 — The Multilingual Hybrid Sync Update

This major milestone transitions TermSub into a fully language-agnostic, enterprise-ready platform. By coupling the linguistic excellence of Gemini with the frame-accurate timecode precision of WhisperX, version 1.2.0 guarantees flawless subtitle alignment across multiple languages without hardware strain.

🚀 What's New

• Hybrid Alignment Pipeline (Gemini + WhisperX): Combines the conceptual speed and nuance of cloud-based Gemini AI for transcript generation with localized WhisperX forced alignment to guarantee frame-accurate sync.
• Bring Your Own Key (BYOK) Architecture: Added a visually clean, client-side masked API Key vault (type="password"). Key states persist via localStorage and route to the backend using secure, screen-share-safe HTTP custom headers.
• 100% Language-Agnostic Infrastructure: Deep-cleaned all database entries, configuration variables, and multi-agent prompts (Director, Glossary, Translator). The app now fully formats academic domains and glossary terms dynamically for any source/target pair (English, German, Persian, Spanish, etc.).
• Smart Audio Auto-Detection: Re-engineered the transcription schema. Gemini now dynamically tags the dominant spoken language in its JSON output, enabling WhisperX to dynamically provision the precise corresponding phoneme model (e.g., loading German or English acoustic profiles dynamically).

⚙️ Fixes & Structural Improvements

• Fixed the cumulative subtitle timestamp drift bug caused by legacy text conditioning constraints.
• Resolved a bleeding-edge Python 3.14 runtime compatibility issue with Pydantic header validation by parsing raw FastAPI incoming request headers.
• Upgraded user layout to feature clean side-by-side comparative engine guides (Local Engine vs Cloud Hybrid Engine) to optimize user decision-making based on machine resources.

TermSub v1.1.0: Gemini Streamline

Release v1.1.0

v1.0.0

Initial Release of TermSub: Specialized AI Video Translation

First-Class RTL Support: Optimized specifically for Persian (Farsi) and other Right-to-Left languages.

Multi-Agent Translation Pipeline: Features a sequence of three specialized agents (Director, Glossary, and Translator) for context-aware and consistent terminology.

Flexible Transcription: Integrated support for Groq (Whisper), Gemini Flash, and Local (faster-whisper) engines.

Built-in Web UI: A complete interface for drag-and-drop uploads and real-time WebSocket progress tracking.

Advanced Terminology Management: Auto-extraction and standardization of key terms across segments.