diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 366 |
1 files changed, 282 insertions, 84 deletions
@@ -1,115 +1,313 @@ -# youtube-local +# yt-local - -youtube-local is a browser-based client written in Python for watching Youtube anonymously and without the lag of the slow page used by Youtube. One of the primary features is that all requests are routed through Tor, except for the video file at googlevideo.com. This is analogous to what HookTube (defunct) and invidious do, except that you do not have to trust a third-party to respect your privacy. The assumption here is that Google won't put the effort in to incorporate the video file requests into their tracking, as it's not worth pursuing the incredibly small number of users who care about privacy. Tor has high latency, so this will not be as fast as regular Youtube. However, using Tor is optional; when not routing through Tor, video pages may load faster than they do with Youtube's laggy page depending on your browser. +[](https://www.gnu.org/licenses/agpl-3.0) +[](https://www.python.org/downloads/) +[](https://git.fridu.us/heckyel/youtube-local) -The Youtube API is not used, so no keys or anything are needed. It uses the same requests as the Youtube webpage. +A privacy-focused, browser-based YouTube client that routes requests through Tor for anonymous viewing—**without compromising on speed or features**. -## Screenshots -[Gray theme](https://user-images.githubusercontent.com/28744867/64483431-8e1c8e80-d1b6-11e9-999c-14d36ddd582f.png) +[Features](#features) • [Install](#install) • [Usage](#usage) • [Screenshots](#screenshots) + +--- -[Dark theme](https://user-images.githubusercontent.com/28744867/64483432-8fe65200-d1b6-11e9-90bd-32869542e32e.png) +> [!NOTE] +> How it works: yt-local mirrors YouTube's web requests (using the same Invidious/InnerTube endpoints as yt-dlp and Invidious) but strips JavaScript and serves a lightweight HTML frontend. No API keys needed. -[Non-Theater mode](https://user-images.githubusercontent.com/28744867/64483433-92e14280-d1b6-11e9-9b56-2ef5d64c372f.png) +## Overview -[Channel](https://user-images.githubusercontent.com/28744867/64483436-95dc3300-d1b6-11e9-8efc-b19b1f1f3bcf.png) +yt-local is a lightweight, self-hosted YouTube client written in Python that gives you: -[Downloads](https://user-images.githubusercontent.com/28744867/64483437-a2608b80-d1b6-11e9-9e5a-4114391b7304.png) +- **Privacy-first**: All requests route through Tor by default (video optional), keeping you anonymous. +- **Fast page loads**: No lazy-loading, no layout reflows, instant comment rendering. +- **Full control**: Customize subtitles, related videos, comments, and playback speed. +- **High quality**: Supports all YouTube video qualities (144p–2160p) via DASH muxing. +- **Zero ads**: Clean interface, no tracking, no sponsored content. +- **Self-hosted**: You control the instance—no third-party trust required. ## Features -* Standard pages of Youtube: search, channels, playlists -* Anonymity from Google's tracking by routing requests through Tor -* Local playlists: These solve the two problems with creating playlists on Youtube: (1) they're datamined and (2) videos frequently get deleted by Youtube and lost from the playlist, making it very difficult to find a reupload as the title of the deleted video is not displayed. -* Themes: Light, Gray, and Dark -* Subtitles -* Easily download videos or their audio -* View or post comments -* Works without Javascript -* Theater and non-theater mode -* Subscriptions that are independent from Youtube - * Works by checking channels individually - * Can be set to automatically check channels. - * For efficiency of requests, frequency of checking is based on how quickly channel posts videos - * Can mute channels, so as to have a way to "soft" unsubscribe. Muted channels won't be checked automatically or when using the "Check all" button. Videos from these channels will be hidden. - * Can tag subscriptions to organize them or check specific tags -* Fast page - * No distracting/slow layout rearrangement - * No lazy-loading of comments; they are ready instantly. -* Settings allow fine-tuned control over when/how comments or related videos are shown: - 1. Shown by default, with click to hide - 2. Hidden by default, with click to show - 3. Never shown - -## Planned features -- [ ] Putting videos from subscriptions or local playlists into the related videos -- [ ] Information about video (geographic regions, region of Tor exit node, etc) -- [ ] Ability to delete playlists -- [ ] Auto-saving of local playlist videos -- [ ] Import youtube playlist into a local playlist -- [ ] Rearrange items of local playlist -- [ ] Muxing of 1080p -- [ ] Corrected .m4a downloads -- [ ] Replying to comment replies -- [ ] Editing comments -- [ ] Indicate if comments are disabled -- [ ] Indicate how many comments a video has -- [ ] Featured channels page -- [ ] Channel comments -- [ ] Video transcript -- [ ] Tor RC -- [ ] Support &t parameter -- [ ] Subscriptions: Option to mark what has been watched -- [ ] Subscriptions: Option to filter videos based on keywords in title or description - -## Installing + +| Category | Features | +|---------------|----------------------------------------------------------------------------------------| +| Core | Search, channels, playlists, watch pages, comments, subtitles (auto/manual) | +| Privacy | Optional Tor routing (including video), automatic circuit rotation on 429 errors | +| Local | Local playlists (durable against YouTube deletions), thumbnail caching | +| UI | 3 themes (Light/Gray/Dark), theater mode, custom font selection | +| Config | Fine-grained settings: subtitle mode, comment visibility, sponsorblock integration | +| Performance | No JavaScript required, instant page rendering, rate limiting with exponential backoff | +| Subscriptions | Import from YouTube Takeout (CSV/JSON), tag organization, mute channels | + +### Advanced Capabilities + +- SponsorBlock integration — skip sponsored segments automatically +- Custom video speeds — 0.25x to 4x playback rate +- Video transcripts — accessible via transcript button +- Video quality muxing — combine separate video/audio streams for non-360p/720p resolutions +- Tor circuit rotation — automatic new identity on rate limiting (429) +- File downloading — download videos/audio (disabled by default, configurable) + +## Screenshots + +| Light Theme | Gray Theme | Dark Theme | +|:----------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------:| +|  |  |  | + +| Channel View | Playlist View | +|:------------------------------------------------------------------------------------------------:|:---------------------:| +|  | *(similar structure)* | + +--- + +## Install ### Windows -Download the zip file under the Releases page. Unzip it anywhere you choose. +1. Download the latest [release ZIP](https://git.fridu.us/heckyel/yt-local/releases) +2. Extract to any folder +3. Run `run.bat` to start + +### GNU/Linux / macOS + +```bash +# 1. Clone or extract the release +git clone https://git.fridu.us/heckyel/yt-local.git +cd yt-local -### Linux/MacOS +# 2. Create and activate virtual environment +python3 -m venv venv +source venv/bin/activate # or `venv\Scripts\activate` on Windows -Download the tarball under the Releases page and extract it. `cd` into the directory and run +# 3. Install dependencies +pip install -r requirements.txt + +# 4. Run the server +python3 server.py ``` -pip3 install -r requirements.txt + +> [!TIP] +> If `pip` isn't installed, use your distro's package manager (e.g., `sudo apt install python3-pip` on Debian/Ubuntu). + +### Portable Mode + +To keep settings and data in the same directory as the app: + +```bash +# Create an empty settings.txt in the project root +touch settings.txt +python3 server.py +# Data now stored in ./data/ instead of ~/.yt-local/ ``` -**Note**: If pip isn't installed, install it according to [this answer](https://unix.stackexchange.com/a/182467), but make sure you run `python3 get-pip.py` instead of `python get-pip.py` +--- ## Usage -Firstly, if you wish to run this in portable mode, create the empty file "settings.txt" in the program's main directory. If the file is there, settings and data will be stored in the same directory as the program. Otherwise, settings and data will be stored in `C:\Users\[your username]\.youtube-local` on Windows and `~/.youtube-local` on Linux/MacOS. +### Basic Access + +1. Start the server: + +```bash +python3 server.py +# Server runs on http://127.0.0.1:9010 (configurable in /settings) +``` + +2. Access YouTube via proxy: + +```bash +http://localhost:9010/https://www.youtube.com/watch?v=vBgulDeV2RU +``` + + All YouTube URLs must be prefixed with `http://localhost:9010/https://`. + +3. (Optional) Use Redirector to auto-redirect YouTube URLs: + + - **Firefox**: [Redirector addon](https://addons.mozilla.org/firefox/addon/redirector/) + - **Chrome**: [Redirector addon](https://chrome.google.com/webstore/detail/redirector/ocgpenflpmgnfapjedencafcfakcekcd) + - **Pattern**: `^(https?://(?:[a-zA-Z0-9_-]*\.)?(?:youtube\.com|youtu\.be|youtube-nocookie\.com)/.*)` + - **Redirect to**: `http://localhost:9010/$1` + +> [!NOTE] +> To use embeds on web pages, make sure "Iframes" is checked under advanced options in your redirector rule. + +### Tor Routing + +> [!IMPORTANT] +> Recommended for privacy. In `/settings`, set **Route Tor** to `"On, except video"` (or `"On, including video"`), then save. + +#### Running Tor + +Option A: Tor Browser (easiest) + +- Launch Tor Browser and leave it running +- yt-local uses port `9150` (Tor Browser default) + +Option B: Standalone Tor + +```bash +# Linux (Debian/Ubuntu) +sudo apt install tor +sudo systemctl enable --now tor + +# Configure yt-local ports (if using default Tor ports): +# Tor port: 9150 +# Tor control port: 9151 +``` + +> [!WARNING] +> Video over Tor is bandwidth-intensive. Consider donating to [Tor node operators](https://torservers.net/donate.html) to sustain the network. -To run the program on windows, open `run.bat`. On Linux/MacOS, run `python3 server.py`. +### Import Subscriptions +1. Go to [Google Takeout](https://takeout.google.com/takeout/custom/youtube) +2. Deselect all → select only **Subscriptions** → create export +3. Download and extract `subscriptions.csv` (path: `YouTube and YouTube Music/subscriptions/subscriptions.csv`) +4. In yt-local: **Subscriptions** → **Import** → upload CSV -Access youtube URLs by prefixing them with `localhost:8080/`, For instance, `http://localhost:8080/https://www.youtube.com/watch?v=vBgulDeV2RU` -You can use an addon such as [Redirector](https://addons.mozilla.org/en-US/firefox/addon/redirector/) to automatically redirect Youtube URLs to youtube-local. I use the include pattern `^(https?://(?:[a-zA-Z0-9_-]*\.)?(?:youtube\.com|youtu\.be)/.*)` and the redirect pattern `http://localhost:8080/$1`. +> [!IMPORTANT] +> The CSV file must contain columns: `channel_id,channel_name,channel_url` -youtube-local can be added as a search engine in firefox to make searching more convenient. See [here](https://support.mozilla.org/en-US/kb/add-or-remove-search-engine-firefox) for information on firefox search plugins. +## Supported formats -### Using Tor +- Google Takeout CSV +- Google Takeout JSON (legacy) +- NewPipe JSON export +- OPML (from YouTube's old subscription manager) -In the settings page, enable "Route Tor". Be sure to save the settings. +--- -Ensure Tor is listening for Socks5 connections on port 9150 (a simple way to accomplish this is by opening the Tor Browser Bundle and leaving it open). Your connections should now be routed through Tor. +## Configuration -Pull requests and issues are welcome +Visit `http://localhost:9010/settings` to configure: + +| Setting | Description | +|--------------------|-------------------------------------------------| +| Route Tor | Off / On (except video) / On (including video) | +| Default subtitles | Off / Manual only / Auto + Manual | +| Comments mode | Shown by default / Hidden by default / Never | +| Related videos | Same options as comments | +| Theme | Light / Gray / Dark | +| Font | Browser default / Serif / Sans-serif | +| Default resolution | Auto / 144p–2160p | +| SponsorBlock | Enable Sponsored segments skipping | +| Proxy images | Route thumbnails through yt-local (for privacy) | + +--- + +## Troubleshooting + +| Issue | Solution | +|------------------------------|----------------------------------------------------------------------------------------------| +| Port already in use | Change `port_number` in `/settings` or kill existing process: `pkill -f "python3 server.py"` | +| 429 Too Many Requests | Enable Tor routing for automatic IP rotation, or wait 5-10 minutes | +| Failed to connect to Tor | Verify Tor is running: `tor --version` or launch Tor Browser | +| Subscriptions not importing | Ensure CSV has columns: `channel_id,channel_name,channel_url` | +| Settings persist across runs | Check `~/.yt-local/settings.txt` (non-portable) or `./settings.txt` (portable) | + +--- + +## Development + +### Running Tests + +```bash +source venv/bin/activate # if not already in venv +make test +``` + +### Project Structure + +```bash +yt-local/ +├── youtube/ # Core application logic +│ ├── __init__.py # Flask app entry point +│ ├── util.py # HTTP utilities, Tor manager, fetch_url +│ ├── watch.py # Video/playlist page handlers +│ ├── channel.py # Channel page handlers +│ ├── playlist.py # Playlist handlers +│ ├── search.py # Search handlers +│ ├── comments.py # Comment extraction/rendering +│ ├── subscriptions.py # Subscription management + SQLite +│ ├── local_playlist.py # Local playlist CRUD +│ ├── proto.py # YouTube protobuf token generation +│ ├── yt_data_extract/ # Polymer JSON parsing abstractions +│ └── hls_cache.py # HLS audio/video streaming proxy +├── templates/ # Jinja2 HTML templates +├── static/ # CSS/JS assets +├── translations/ # i18n files (Babel) +├── tests/ # pytest test suite +├── server.py # WSGI entry point +├── settings.py # Settings parser + admin page +├── generate_release.py # Windows release builder +└── manage_translations.py # i18n maintenance script +``` + +> [!NOTE] +> For detailed architecture guidance, see [`docs/HACKING.md`](docs/HACKING.md). + +### Contributing + +Contributions welcome! Please: + +1. Read [`docs/HACKING.md`](docs/HACKING.md) for coding guidelines +2. Follow [PEP 8](https://peps.python.org/pep-0008/) style (use `ruff format`) +3. Run tests before submitting: `pytest` +4. Ensure no security issues: `bandit -r .` +5. Update docs for new features + +--- + +## Security Notes + +- **No API keys required** — uses same endpoints as public YouTube web interface +- **Tor is optional** — disable in `/settings` if you prefer performance over anonymity +- **Rate limiting handled** — exponential backoff (max 5 retries) with automatic Tor circuit rotation +- **Path traversal protected** — user input validated against regex whitelists (CWE-22) +- **Subprocess calls secure** — build scripts use `subprocess.run([...])` instead of shell (CWE-78) + +> [!NOTE] +> GPG key for release verification: `72CFB264DFC43F63E098F926E607CE7149F4D71C` + +--- + +## Public Instances + +yt-local is designed for self-hosting. + +--- + +## Donate + +This project is 100% free and open-source. If you'd like to support development: + +- **Bitcoin**: `1JrC3iqs3PP5Ge1m1vu7WE8LEf4S85eo7y` +- **Tor node donation**: <https://torservers.net/donate> + +--- ## License -This project is licensed under the GNU Affero General Public License v3 (GNU AGPLv3) or any later version. - -Permission is hereby granted to the youtube-dl project at [https://github.com/rg3/youtube-dl](https://github.com/rg3/youtube-dl) to relicense any portion of this software under the Unlicense, public domain, or whichever license is in use by youtube-dl at the time of relicensing, for the purpose of inclusion of said portion into youtube-dl. Relicensing permission is not granted for any purpose outside of direct inclusion into the [official repository](https://github.com/rg3/youtube-dl) of youtube-dl. If inclusion happens during the process of a pull-request, relicensing happens at the moment the pull request is merged into youtube-dl; until that moment, any cloned repositories of youtube-dl which make use of this software are subject to the terms of the GNU AGPLv3. - -## Similar projects -- [youtube-dl](https://rg3.github.io/youtube-dl/), which this project is based off -- [invidious](https://github.com/omarroth/invidious) Nearly identical to this project. More polished and with more features. -- [NewPipe](https://newpipe.schabi.org/) (app for android) -- [mps-youtube](https://github.com/mps-youtube/mps-youtube) (terminal-only program) -- [youtube-viewer](https://github.com/trizen/youtube-viewer) -- [FreeTube](https://github.com/FreeTubeApp/FreeTube) (Similar to this project, but is an electron app outside the browser) -- [smtube](https://www.smtube.org/) -- [Minitube](https://flavio.tordini.org/minitube), [github here](https://github.com/flaviotordini/minitube) -- [toogles](https://github.com/mikecrittenden/toogles) (only embeds videos, doesn't use mp4) -- [goyt](https://gitgud.io/m712/goyt/) +GNU Affero General Public License v3.0+ + +See [`LICENSE`](LICENSE) for full text. + +### Exception for youtube-dl + +Permission is granted to relicense code portions into youtube-dl's license (currently GPL) for direct inclusion into the [official youtube-dl repository](https://github.com/ytdl-org/youtube-dl). This exception **does not apply** to forks or other uses—those remain under AGPLv3. + +--- + +## Similar Projects + +| Project | Type | Notes | +|--------------------------------------------------------------|----------|--------------------------------------| +| [invidious](https://github.com/iv-org/invidious) | Server | Multi-user instance, REST API | +| [Yotter](https://github.com/ytorg/Yotter) | Server | YouTube + Twitter integration | +| [FreeTube](https://github.com/FreeTubeApp/FreeTube) | Desktop | Electron-based client | +| [NewPipe](https://newpipe.schabi.org/) | Mobile | Android-only, no JavaScript | +| [mps-youtube](https://github.com/mps-youtube/mps-youtube) | Terminal | CLI-based, text UI | +| [youtube-local](https://github.com/user234683/youtube-local) | Browser | Original project (base for yt-local) | + +--- + +Made for privacy-conscious users + +Last updated: 2026-05-03 |