Metadata-Version: 2.4
Name: ytextract
Version: 0.0.2
Summary: Python 3 library for downloading YouTube Videos.
Home-page: https://github.com/Josh-XT/ytextract
Author: Josh-XT
License: The Unlicense (Unlicense)
Project-URL: Bug Reports, https://github.com/Josh-XT/ytextract/issues
Keywords: youtube,download,video,stream
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python
Classifier: Topic :: Internet
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: selenium
Requires-Dist: webdriver-manager
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: pydantic
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# ytextract

*ytextract* is a genuine, lightweight Python library (and command-line utility) for downloading YouTube videos.

## Description

YouTube is the most popular video-sharing platform in the world and as a hacker, you may encounter a situation where you want to script something to download videos. For this, I present to you: *ytextract*.

*ytextract* is a lightweight library written in Python. It has minimal dependencies and aims to be highly reliable.

*ytextract* also makes pipelining easy, allowing you to specify callback functions for different download events, such as ``on progress`` or ``on complete``.

Furthermore, *ytextract* includes a command-line utility, allowing you to download videos right from the terminal.

## Features

- Support for both progressive & DASH streams
- Easily register ``on_download_progress`` & ``on_download_complete`` callbacks
- Command-line interface included
- Caption track support
- Outputs caption tracks to .srt format (SubRip Subtitle)
- Ability to capture thumbnail URL
- Extensively documented source code

## Quickstart

### Installation

ytextract requires an installation of Python 3.7 or greater, as well as pip. (Pip is typically bundled with Python [installations](https://python.org/downloads).) If installing from source, git is also required.

To install from PyPI with pip:

```bash
pip install ytextract
```

Or install from source:

```bash
git clone https://github.com/Josh-XT/ytextract
pip install -e .
```

### Using the command-line interface

Use the `ytextract` command in a terminal to download videos, captions, or multiple videos from a list or channel.

#### Download a single video

To download a video at the highest progressive quality, you can use the following command:

```bash
ytextract https://youtube.com/watch?v=2lAe1cqCOXo
```

#### Download captions for a video

To download only captions for a video, use the `--captions` flag:

```bash
ytextract --captions https://youtube.com/watch?v=2lAe1cqCOXo
```

#### Download Videos from a list in a text file

To download multiple videos from a text file containing YouTube video URLs (one URL per line), use the `--file` flag:

```bash
ytextract --file videos.txt
```

#### Download Videos from a Channel, or multiple Channels

To download all videos from one or more YouTube channels, use the `--channels` flag followed by the channel usernames:

```bash
ytextract --channels officialalphablocks Numberblocks
```

### YouTube Proxy Server

ytextract includes a built-in proxy server that can cache and stream YouTube videos over your local network. This is perfect for:

- **Home NAS setups** - Run the server on your NAS and stream videos to devices with restricted internet access
- **Limited bandwidth connections** - Download videos once and stream locally for repeat watches, saving bandwidth
- **Offline viewing** - Pre-download videos and serve them to devices without internet access
- **Parental controls** - Restrict direct YouTube access while still allowing curated content

#### Starting the server

Start the server in the foreground:

```bash
ytextract --server start
```

Start the server in the background (daemon mode):

```bash
ytextract --server start --daemon
```

You can also specify a custom host and port:

```bash
ytextract --server start --host 0.0.0.0 --port 8765 --daemon
```

#### Stopping the server

```bash
ytextract --server stop
```

#### Checking server status

```bash
ytextract --server status
```

#### API Endpoints

Once the server is running, you can access the following endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | API information and available endpoints |
| `/health` | GET | Health check |
| `/watch?v={video_id}` | GET | Stream a video (auto-downloads if not cached) |
| `/download/video` | POST | Download a video by URL |
| `/download/captions` | POST | Download captions only |
| `/download/file` | POST | Download videos from a file |
| `/download/channels` | POST | Download videos from channels |

#### Streaming videos

To stream a video, simply navigate to:

```
http://your-server:8765/watch?v=VIDEO_ID
```

If the video is already cached locally, it streams immediately. If not, it downloads the video first and then streams it. You can also specify a language for captions:

```
http://your-server:8765/watch?v=VIDEO_ID&language=en-US
```

#### Example: Download and stream a video via API

```bash
# Download a video
curl -X POST http://localhost:8765/download/video \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=VIDEO_ID", "language": "en-US"}'

# Stream the video in a browser
# Open: http://localhost:8765/watch?v=VIDEO_ID
```


### Using ytextract in a Python script

To download a video using the library in a script, simply import ytextract and call the helper functions directly.

#### Download a single video

Set the `url` parameter to the YouTube video URL you wish to download.

```python
import ytextract

ytextract.download(url="https://www.youtube.com/watch?v=VIDEO_ID")
```

#### Download captions for a video

Set the `url` parameter to the YouTube video URL you wish to download captions for.

```python
import ytextract

ytextract.download_captions(url="https://www.youtube.com/watch?v=VIDEO_ID")
```

#### Download Videos from a list from videos.txt

You can change the filename argument to any text file containing YouTube video URLs (one URL per line).

```python
import ytextract

ytextract.download_videos_from_list(filename="videos.txt")
```

#### Download Videos from a Channel, or multiple Channels

You can specify one or more channel usernames in the `channels` parameter to download all videos from those channels.

```python
import ytextract

ytextract.download_videos_from_channels(channels=["officialalphablocks", "Numberblocks"])
```

## License

This project is licensed under The Unlicense - see the [LICENSE](LICENSE) file for details.

## Contributing

Feel free to open an issue or a pull request at https://github.com/Josh-XT/ytextract
