DNT-YT (Do-Not-Track YouTube) is a lightweight YouTube caching + offline browsing API.
Inspired by Piped and Invidious. However, their goals and typical use-cases differ from what I need, so I created DNT-YT.
DNT-YT prioritizes offline YouTube video exploration above everything else. In fact, this is the only purpose of the source code in this repository.
-
Accepts various YouTube URL formats (or a raw
video_id) -
Automatically requests caching when missing
-
Stores cached media (video/audio, thumbnail and subtitles) and serves them as browser-playable URLs
-
Serves an HTML watch page that:
- polls cache status every 5 seconds when not ready
- auto-plays video (muted) once ready
- uses a Mute/Unmute toggle as the user gesture to enable audio
- keeps A/V synchronized in the browser (no FFmpeg)
- supports thumbnails and multilingual subtitles
- API: FastAPI
- Queue: RQ
- Storage/State: Redis (jobs/status) + local media volume
- Downloader: yt-dlp (caching audio/video separately; no FFmpeg required)
These routes render the HTML player page. If the cache is missing, the server should enqueue a caching job automatically, then the page waits/polls until the cache becomes ready.
/wLp_c3M-nPA
/watch/wLp_c3M-nPA
/watch?v=wLp_c3M-nPA
/watch?url=https://www.youtube.com/watch?v=wLp_c3M-nPA
Queues a cache job if missing.
GET /v1/yt/play?url=<youtube_url>
Example:
curl "http://localhost:58000/v1/yt/play?url=https://www.youtube.com/watch?v=wLp_c3M-nPA"Typical response:
{
"ok": true,
"ready": false,
"video_id": "wLp_c3M-nPA",
"job_id": "..."
}Returns whether cache is ready and (when ready) URLs for cached media.
GET /v1/yt/status?video_id=<video_id>
Example:
curl "http://localhost:58000/v1/yt/status?video_id=wLp_c3M-nPA"Typical response:
{
"ok": true,
"ready": true,
"video_id": "wLp_c3M-nPA",
"video_url": "/media/wLp_c3M-nPA/video",
"audio_url": "/media/wLp_c3M-nPA/audio",
}These URLs are browser-playable once caching completes.
GET /media/<video_id>/video
GET /media/<video_id>/audio
GET /media/<video_id>/thumbnail # thumbnail image
GET /media/<video_id>/subtitles # the list of all subtitles
GET /media/<video_id>/subtitles/<lang> # subtitles (vtt format)
Example:
/media/wLp_c3M-nPA/video
/media/wLp_c3M-nPA/audio
/media/wLp_c3M-nPA/thumbnail # thumbnail image
/media/wLp_c3M-nPA/subtitles # the list of all subtitles
/media/wLp_c3M-nPA/subtitles/en # subtitles (vtt format)
DNT-YT can decide response format based on request headers. Typical behavior:
- If the client requests
text/html, return the watch page - If the client requests
application/json, return JSON (status or play response) - (Optional)
oEmbed/ OpenGraph can be added for social previews
DNT-YT downloads audio and video separately using yt-dlp and serves them as separate files.
The watch page:
- starts video playback automatically (usually requires
mutedfor autoplay) - uses a Mute/Unmute toggle button as the explicit user action to enable audio reliably
- keeps audio aligned to video time (periodic drift correction and seek sync)
This avoids any server-side muxing/merging and therefore avoids FFmpeg.
- yt-dlp (required)
- Redis
- FastAPI / Uvicorn
- RQ
Typical:
docker compose up --buildThen open:
- Watch page:
http://localhost:58000/wLp_c3M-nPA - API:
http://localhost:58000/v1/yt/play?url=...
Goals
- Offline-first YouTube exploration
- Simple caching API
- Browser-playable cached URLs
- Minimal server-side processing (no FFmpeg)
Non-goals
- Full UI like a Piped or Invidious
- Account features / subscriptions / comments
- Complex transcoding pipelines
For scenarios where a CDN is used for long-distance data transfer, it is recommended to configure appropriate cache rules to reduce bandwidth usage and improve performance.
The following example shows a cache rule configuration based on Cloudflare:
(http.request.full_uri wildcard r"https://domain.tld/media/*/video")
or
(http.request.full_uri wildcard r"https://domain.tld/media/*/audio")
or
(http.request.full_uri wildcard r"https://domain.tld/media/*/thumbnail")
- https://dnt-yt.catswords.net/wLp_c3M-nPA (SKC VHS Visual Doctor)
- https://dnt-yt.catswords.net/kvAfmYNtugQ (Dolby Atmos Sample Video)
- https://dnt-yt.catswords.net/mkggXE5e2yk (LG TV Sample Video)
This software is licensed under the GNU General Public License v3.0 and is provided without any warranty, to the extent permitted by applicable law. See the GPL v3.0 license for details.
The authors and contributors shall not be held liable for any damages arising from the use of this software. Any illegal or unauthorized use is solely the responsibility of the user, who must ensure compliance with all applicable laws and regulations.
I am always open. Collaboration, opportunities, and community activities are all welcome.
