How o-nos/reclip works
1. Overall shape
- ReClip is a small, self-hosted Flask application with a server-rendered web UI.
- The architecture is intentionally minimal: one Python backend, one HTML template, a static asset folder, and no database or build pipeline.
2. Primary entry points
- app.py is the core application and likely contains all HTTP routes and download orchestration.
- reclip.sh is the local startup wrapper used for running the app outside Docker.
- Dockerfile packages the same app for containerized deployment.
3. Frontend subsystem
- templates/index.html provides the entire user interface.
- static/ holds browser-served assets such as CSS/JS and any page-specific resources.
- The UI is vanilla HTML/CSS/JS, so the browser talks directly to the Flask backend without a separate frontend service.
4. Backend request flow
- The user pastes one or more URLs into the web UI.
- The browser sends those URLs to Flask.
- The backend uses yt-dlp to inspect the links, extract metadata, and determine available formats.
- The backend returns video/audio info, thumbnails, and quality options to the UI.
5. Download subsystem
- Actual media retrieval is delegated to yt-dlp.
- Audio extraction and video conversion depend on ffmpeg, which is an external runtime dependency rather than an in-repo component.
- Downloads are exposed to the user as MP4 or MP3 outputs, with quality selection for available formats.
6. Bulk and deduplication behavior
- The app supports multiple URLs in one submission.
- URL deduplication happens in the application layer so repeated links are not processed redundantly.
- This suggests a request-scoped workflow rather than a persistent job queue or task store.
7. Data and state boundaries
- There is no database, cache layer, or long-lived storage visible in the repo.
- State appears to be transient: fetched metadata, selected formats, and generated downloads exist only during the request/session flow.
- The system is therefore stateless at the infrastructure level, aside from temporary download artifacts handled during processing.
8. External dependencies and services
- yt-dlp is the main external engine for site compatibility and metadata extraction across 1000+ supported platforms.
- ffmpeg handles media processing/conversion.
- The app does not depend on any external SaaS APIs; it operates entirely on user-supplied URLs and local tooling.
9. Deployment model
- The app is designed to run locally or in a container on port 8899.
- Docker provides a self-contained runtime boundary for shipping Python plus system-level media tooling.
- The README’s “single Python file backend” indicates the deployment footprint is intentionally small.
10. Repository structure significance
- assets/ contains preview media for documentation and does not participate in runtime request handling.
- LICENSE and README.md are documentation/supporting files.
- The architecture is centered almost entirely around one application path: browser UI → Flask backend → yt-dlp/ffmpeg → downloadable media response.
11. What to draw in an architecture diagram
- Show a client browser talking to a Flask web app.
- Show Flask invoking yt-dlp for metadata and downloads, and ffmpeg for conversion.
- Show the response path returning thumbnails, format choices, and downloadable MP4/MP3 files.
- Do not include databases, message queues, or separate frontend services, because this repo does not contain them.
Main entry points: app.py Flask App · index.html Main UI · reclip.sh Startup Script · Dockerfile Container Image
Components 12
User Interface
Server-rendered browser UI and served static assets.
- Browser · User submits URLs and receives results in the web UI.
- Main UI · Server-rendered page for URL entry, results, and download actions.
templates/index.html - Static Assets · CSS, JS, and other files served directly to the browser.
static
Application Core
Single Flask app that handles requests and download orchestration.
- Flask App · Primary application entry point and request handler.
app.py - URL Dedupe · Removes repeated URLs within a submission before processing.
app.py - Metadata Probe · Extracts video metadata, thumbnails, and format information.
app.py - Format Picker · Chooses available audio/video qualities and output options.
app.py - Download Flow · Coordinates fetching media and preparing MP4 or MP3 outputs.
app.py
Runtime & Deploy
Local and container launch paths for the app.
- Startup Script · Local launch helper for running the app outside Docker.
reclip.sh - Container Image · Packages the Python app and system dependencies for containerized runs.
Dockerfile
External Tools
System tools invoked by the app for media extraction and conversion.
- yt-dlp · External engine for platform compatibility, metadata extraction, and media downloads.
- ffmpeg · External runtime used for audio extraction and video conversion.
Connections 14
- Browser → Main UI: view · User loads the main page in a browser.
- Browser → Flask App: submit URLs · Browser sends submitted links and options to the Flask backend.
- Main UI → Static Assets: load assets · The page references browser-served styling and scripting assets.
- Flask App → URL Dedupe: normalize list · Backend removes duplicate URLs before processing.
- URL Dedupe → Metadata Probe: inspect links · Unique URLs are probed for metadata and available formats.
- Metadata Probe → yt-dlp: probe · yt-dlp provides site support and metadata extraction.
- Metadata Probe → Format Picker: formats · Extracted metadata feeds the quality and output selection logic.
- Format Picker → Download Flow: choose output · Selected format determines the download/conversion path.
- Download Flow → yt-dlp: fetch media · yt-dlp performs the actual media retrieval.
- Download Flow → ffmpeg: convert · ffmpeg handles audio extraction and video conversion.
- Download Flow → Flask App: response · Prepared media and result data are returned to the web layer.
- Flask App → Browser: results · Browser receives thumbnails, quality options, and download links/files.
- Startup Script → Flask App: run locally · Shell wrapper starts the Flask application outside containers.
- Container Image → Flask App: package run · Container image ships the app with its runtime dependencies.