# 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