hythzx/video-downloader-api repository overview

⁠Frame Video Studio

A self-hosted, multi-platform video, audio, and subtitle downloader.

Frame Video Studio brings X / Twitter, YouTube, and Bilibili into one clean, responsive interface. Paste a media URL, inspect available formats, and download the content you want to keep. Powered by yt-dlp, FastAPI, FFmpeg, Vue 3, and Nginx.

GitHub Repository⁠ · Documentation⁠

⁠Docker images

Frame Video Studio is published as two images. The same API image is used to run a separate background worker.

Deploy all three services: Web + API + Worker. The existing Docker image names are intentionally retained for compatibility, even though the GitHub repository is now called Frame-Video-Studio.

⁠Features

• Multi-platform support: X / Twitter, YouTube, and Bilibili.
• Video downloads: Choose an available resolution and save MP4 media. Where required, FFmpeg merges separate video and audio streams.
• Audio extraction: Export MP3 or M4A when a usable audio track is available.
• Subtitle downloads: Save source-provided human or automatically generated captions as SRT or VTT.
• Background video jobs: Create video download tasks and check their status instead of keeping a single HTTP request open for the entire download.
• Recent extraction history: Browse recently parsed media and reopen an item.
• Optional private X bookmarks: Browse your own X bookmarks using server-side login cookies, filter video posts, and download selected video posts individually or in small ZIP batches.
• Self-hosted storage: SQLite metadata and finished background video downloads use a persistent Docker volume.

⁠Supported platforms

Actual availability depends on the media, platform permissions, your region, login state, and yt-dlp extractor compatibility. DRM-protected content is not supported.

⁠Quick start with Docker Compose

Recommended: Use the current Compose configuration from the repository. It contains the required web, api, and worker services and a shared persistent volume.

git clone https://github.com/hythzx/Frame-Video-Studio.git
cd Frame-Video-Studio

cp .env.example .env
docker compose pull
docker compose up -d

Open http://127.0.0.1:8080⁠ on the Docker host.

The Web UI binds to localhost only by default. For access from another device, update BIND_ADDRESS and configure HTTPS and authentication using a trusted reverse proxy.

Check services and logs:

docker compose ps
docker compose logs -f api worker web

Update to current images:

git pull origin main
docker compose pull
docker compose up -d

⁠Configuration

Edit the server-local .env file as needed.

For private X bookmarks, configure your own account's auth_token and ct0 under TWITTER_COOKIES and generate a separate Frame access token locally:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Store credentials only in the server's .env file. Never commit credentials or share them in public logs or screenshots. The X bookmarks integration uses unofficial web endpoints, may be rate-limited, and can stop working when X changes its website.

⁠How the containers work

Browser
  │
  ▼
Web (Vue 3 + Nginx)
  │
  ▼
API (FastAPI + yt-dlp)
  ├── Media extraction and recent history
  ├── Audio and subtitle downloads
  └── Video download task → SQLite
                               │
                               ▼
                      Worker (yt-dlp + FFmpeg)
                               │
                               ▼
                      Persistent /data volume
                               │
                               ▼
                      Completed MP4 download

The API and Worker share the frame-data Docker volume. Keep that volume when updating containers; removing it deletes application data and stored downloads.

⁠Important current limitations

• Only video has been migrated to the background-task workflow. Audio, subtitles, and bookmark ZIP downloads still run through synchronous requests and may time out on slow connections.
• Video jobs currently support status polling and completed-file downloads; SSE progress streaming, task cancellation/retry, and automatic cleanup of old task files are not yet implemented.
• Private bookmark browsing is optional, read-only, and based on unofficial X web interfaces. It requires your own valid account cookies and does not guarantee continued availability.
• The application is intended for personal, self-hosted use. The FRAME_ACCESS_TOKEN protects only private bookmark endpoints, not the entire site. Add authentication, HTTPS, and appropriate rate controls before exposing it on another network.

⁠API overview

For details, see the project README⁠.

⁠Source, releases and license

• Source code: https://github.com/hythzx/Frame-Video-Studio⁠
• Docker Compose: https://github.com/hythzx/Frame-Video-Studio/blob/main/compose.yaml⁠
• Build pipeline: https://github.com/hythzx/Frame-Video-Studio/actions⁠
• Architectures: linux/amd64 and linux/arm64
• Tags: latest from the main branch, commit SHA tags, and semantic version tags for v* releases

Please review the repository for licensing details. Download only content that you have permission to access and save.

Frame Video Studio — Save media from the platforms you love, in one place.