c6c8030907
All checks were successful
CI / test (push) Successful in 52s
* Add complete Spanish translation (README.es.md) * Restructure English README for clarity and conciseness * Filter out YouTube Shorts from channel video listings (sort=4) * Add fallback for video count using playlist metadata when API returns zero * Add get_playlist_metadata() to fetch metadata without full video list * Add is_short() utility to detect YouTube Shorts by duration, badges, and type * Export is_short from yt_data_extract for use across modules
169 lines
5.4 KiB
Markdown
169 lines
5.4 KiB
Markdown
# yt-local
|
|
|
|
A local YouTube client that runs on your machine. No ads, no JavaScript, with Tor support.
|
|
|
|
<p align="center">
|
|
<a href="#features">Features</a> •
|
|
<a href="#installation">Installation</a> •
|
|
<a href="#usage">Usage</a> •
|
|
<a href="#tor">Tor</a> •
|
|
<a href="#development">Development</a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## What is it?
|
|
|
|
yt-local is a local web server that acts as a proxy between your browser and YouTube. Pages load fast, without ads or tracking. Requests can optionally go through Tor.
|
|
|
|
**It doesn't use the YouTube API.** It makes the same requests the normal website would, minus all the rest.
|
|
|
|
## Features
|
|
|
|
- Anonymous browsing with **optional Tor**
|
|
- No ads or JavaScript required
|
|
- Three themes: light, gray, dark
|
|
- Local playlists (videos aren't lost when YouTube removes them)
|
|
- Subscription system independent from YouTube
|
|
- Subtitle support
|
|
- SponsorBlock segments skipped automatically
|
|
- Qualities from 144p to 2160p with HLS support
|
|
- Video download (disabled by default)
|
|
- Comments load instantly, no lazy-loading
|
|
|
|
## Installation
|
|
|
|
### Linux / macOS
|
|
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
python server.py
|
|
```
|
|
|
|
### Windows
|
|
|
|
Download the zip from [Releases](https://github.com/user234683/youtube-local/releases) and run `run.bat`.
|
|
|
|
### With Make
|
|
|
|
```bash
|
|
make install # Dependencies
|
|
make dev # Server
|
|
make test # Tests
|
|
make help # All commands
|
|
```
|
|
|
|
## Usage
|
|
|
|
The server starts at `http://localhost:9010/`
|
|
|
|
To watch a video, prefix the YouTube URL:
|
|
|
|
```
|
|
http://localhost:9010/https://www.youtube.com/watch?v=VIDEO_ID
|
|
```
|
|
|
|
### Redirector
|
|
|
|
You can use a browser extension like [Redirector](https://github.com/einaregilsson/Redirector) to redirect YouTube automatically:
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| Pattern | `^(https?://(?:[a-zA-Z0-9_-]*\.)?(?:youtube\.com|youtu\.be|youtube-nocookie\.com)/.*)` |
|
|
| Redirect to | `http://localhost:9010/$1` |
|
|
| Mode | Regular expression |
|
|
|
|
Enable "Iframes" in advanced options so embedded videos work too.
|
|
|
|
### Portable mode
|
|
|
|
Create an empty `settings.txt` file in the main directory. All settings and data will be stored there instead of `~/.yt-local`.
|
|
|
|
## Tor
|
|
|
|
### Quick option: Tor Browser
|
|
|
|
Open Tor Browser and leave it running. In yt-local settings set "Route Tor" to "On, except video".
|
|
|
|
### Standalone Tor
|
|
|
|
**Debian/Ubuntu:**
|
|
```bash
|
|
sudo apt install tor
|
|
sudo systemctl start tor
|
|
```
|
|
Change the Tor port to `9050` in settings.
|
|
|
|
**Windows:**
|
|
Create a shortcut with: `tor.exe SOCKSPort 9150 ControlPort 9151`
|
|
|
|
### Video routing through Tor
|
|
|
|
Set "Route Tor" to "On, including video". It's slower and consumes Tor bandwidth — consider [donating to Tor nodes](https://torservers.net/donate.html).
|
|
|
|
## Import subscriptions
|
|
|
|
1. Go to [Google Takeout](https://takeout.google.com/takeout/custom/youtube)
|
|
2. Select only "subscriptions" and download the CSV
|
|
3. In yt-local, import the file from the subscriptions manager
|
|
|
|
Supported formats: Google Takeout CSV, NewPipe JSON, OPML, and old Google Takeout JSON.
|
|
|
|
## Development
|
|
|
|
```
|
|
yt-local/
|
|
├── server.py # Entry point, WSGI server
|
|
├── settings.py # Configuration management
|
|
├── youtube/
|
|
│ ├── util.py # Utility functions, Tor routing
|
|
│ ├── watch.py # Video page
|
|
│ ├── channel.py # Channel pages
|
|
│ ├── search.py # Search
|
|
│ ├── subscriptions.py # Subscriptions (SQLite)
|
|
│ ├── local_playlist.py # Local playlists
|
|
│ ├── yt_data_extract/ # YouTube JSON parser
|
|
│ └── ...
|
|
├── tests/ # Tests with pytest
|
|
└── docs/HACKING.md # Development guide
|
|
```
|
|
|
|
### Useful commands
|
|
|
|
```bash
|
|
make test # Run tests
|
|
make lint # Check style
|
|
make i18n-extract # Extract strings
|
|
make i18n-init LANG_CODE=fr # New language
|
|
make i18n-compile # Compile translations
|
|
```
|
|
|
|
Python **3.8+** required. Code follows PEP 8. Commit messages should be descriptive.
|
|
|
|
### Compatibility Notes
|
|
|
|
- **Python 3.8+**: Minimum required version
|
|
- **HLS**: Experimental streaming support for multi-audio videos
|
|
- **Channels with limitations**: Some channels return few videos per response. This is YouTube behavior, not yt-local. The project uses YouTube's internal API (innertube), **not the public YouTube API**.
|
|
|
|
## License
|
|
|
|
GNU AGPLv3 or later. See [LICENSE](LICENSE).
|
|
|
|
## Similar projects
|
|
|
|
- [invidious](https://github.com/iv-org/invidious) Similar to this project, but also allows it to be hosted as a server to serve many users
|
|
- [Yotter](https://github.com/ytorg/Yotter) Similar to this project and to invidious. Also supports Twitter
|
|
- [FreeTube](https://github.com/FreeTubeApp/FreeTube) (Similar to this project, but is an electron app outside the browser)
|
|
- [youtube-local](https://github.com/user234683/youtube-local) first project on which yt-local is based
|
|
- [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)
|
|
- [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)
|
|
- [YTLibre](https://git.sr.ht/~heckyel/ytlibre) only extract video
|
|
- [youtube-dl](https://rg3.github.io/youtube-dl/), which this project was based off
|