Transcript Flow is a fast, anonymous, infrastructure-grade utility that extracts transcripts from video links and delivers clean downloadable files. It is designed as a high-performance backend-first system with interfaces for both the Web and Telegram.
Core Value: Fast → Reliable → Structured → Downloadable.
- Multi-Platform Support: Extract transcripts from YouTube and Vimeo instantly.
- Clean Formats: Download as TXT, PDF, and DOCX, or SRT / VTT subtitles with cue timings. Files are named after the video title.
- 23 Languages: Pick the transcript language on the web or with
/languagein Telegram. YouTube auto-translates when a video has no captions in that language; Vimeo uses the uploader's tracks. - AI Summaries: Optional TL;DR, key points and timestamped chapters via Claude (set
ANTHROPIC_API_KEY; cached per video and language, separately rate limited). - AI Cleanup & Exports: Claude can rewrite raw auto-captions as readable text (punctuation, paragraphs, speaker labels) or turn a video into study notes, a blog post or show notes via
POST /api/v1/enhance. Results download as TXT, DOCX or PDF; cached per video, language and mode, with their own rate limit (RATE_LIMIT_ENHANCE_REQUESTS). - Timestamps: Toggle perfectly formatted timestamps on or off.
- Anonymous & Secure: No accounts required. Generated files auto-delete after ~1 hour (TTL). Optional short-term caption cache (
TRANSCRIPT_CACHE_TTL_HOURS) is pruned by the same cleanup loop. - Rate Limited & Guardrailed: Separate extract vs convert quotas (shared across workers and the bot via optional Redis), max video duration (with caption-based fallback), segment/size caps, and timeout protections.
- Telemetry & Analytics: Built-in lightweight JSON-structured logging and analytics tracking.
Transcript Flow is built with a strict separation of concerns, heavily prioritizing backend modularity for future AI expansion.
- Backend Logic (Brain): Python & FastAPI
- Web Interface: Next.js & React (TailwindCSS)
- Telegram Interface:
python-telegram-bot
transcript/
├── app/ # Python Backend (FastAPI + Telegram Bot)
│ ├── api/ # FastAPI routing (v1 endpoints, metrics)
│ ├── bot/ # Telegram bot logic (handlers, components)
│ ├── services/ # Core business logic (Extract, Format, File, Rate Limit)
│ ├── core/ # Config, Errors, Dependencies
│ ├── utils/ # Logging, Regex Validators
│ └── main.py # FastAPI entry point
├── web/ # Next.js Frontend (React, Tailwind)
│ ├── app/ # App Router pages (/, /app)
│ ├── components/ # React Components (Hero, UI elements)
│ └── public/ # Static assets & branding
├── tests/ # Unit testing suite
├── Dockerfile # Render deployment configuration for Backend
└── requirements.txt # Python dependencies
A premium, modern SaaS web app interface designed with:
- 3D Video Carousel hero section.
- Preview-First Results Flow: Shows a snippet of the transcript immediately, followed by format selection (TXT/PDF/DOCX/SRT/VTT).
- Clean state-machine interactions (Idle → Processing → Success/Error).
A seriously structured, minimal utility bot:
- Instant Processing: Send a URL, get a file. No conversational fluff.
-
Remembered Preferences: Remembers your preferred format (e.g., PDF) and timestamp setting — in Redis when
REDIS_URLis set (kept ~90 days), otherwise in memory until the bot restarts. -
Single Message UX: Status updates (Extracting...
$\rightarrow$ Formatting...$\rightarrow$ Ready) happen within a single edited message to keep chat history clean. -
Branded Onboarding: Clean
/startexperience with inline keyboard routing.
Both the Web App and Telegram Bot route through the identical core service modules (TranscriptService, FileService, etc.) guaranteeing total consistency.
- Backend: Python 3.12, FastAPI, Uvicorn, Gunicorn
- Frontend: Next.js 16, React 19, Tailwind CSS
- Transcripts:
youtube-transcript-api - Generators:
reportlab(PDF),python-docx(Word) - Deployment: Docker, designed for Render/Railway scaling.
- Python 3.12+
- Node.js 18+
# Clone the repository and setup virtual environment
python -m venv venv
source venv/bin/activate # OR venv\Scripts\activate on Windows
# Install dependencies
pip install -r requirements.txt
# Create environment configuration
cp .env.example .env
# Edit .env and supply your TELEGRAM_BOT_TOKEN and other overridesRun the FastAPI Server:
uvicorn app.main:app --reload --port 8000Run the Telegram Bot:
python -m app.bot.telegram_botcd web
# Install dependencies
npm install
# Run the Next.js dev server
npm run devThe web app will be available at http://localhost:3000.
The Phase 1 MVP comes with production-grade guardrails:
- Error Envelopes: Unified structured JSON error responses.
- Timeout Protection:
asyncio.wait_for()applied to upstream transcript providers. - Threadpool Offloading: CPU-bound tasks (PDF/DOCX generation) use asynchronous threading logic so the event loop never blocks.
- Strict Headers: Fully configurable proxy depth and CORS security.
- Sentry Integration: Exception tracking supported via
SENTRY_DSN.
© 2026 Transcript Flow. All rights reserved.