Metadata-Version: 2.4
Name: x-dl
Version: 0.1.0
Summary: Download videos from X (formerly Twitter) - works like a mini yt-dlp
License-Expression: MIT
Keywords: twitter,x,video,downloader,cli
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# x-dl - X (Twitter) video downloader

A tiny, dependency-free Python CLI that downloads videos from X (formerly
Twitter). Works like a mini [yt-dlp](https://github.com/yt-dlp/yt-dlp): give it
a tweet URL, it downloads the video to the folder you choose.

## Install

Requires Python 3.9+.

```bash
# from PyPI (once published)
pip install x-dl

# or straight from a git repo
pip install git+https://github.com/your-username/twitter-downloader.git

# or locally, from a clone
pip install .
```

This puts the `x-dl` command on your PATH. `pipx install x-dl` works too and
keeps it isolated in its own environment.

## Usage

```bash
# download best quality to the current folder
x-dl https://x.com/user/status/1234567890123456789

# download to a specific folder
x-dl https://x.com/user/status/1234567890123456789 -o ~/Videos

# list available formats without downloading (like yt-dlp -F)
x-dl -F https://x.com/user/status/1234567890123456789

# pick a specific format
x-dl -f http-2176 https://x.com/user/status/1234567890123456789 -o ~/Videos

# several tweets at once
x-dl URL1 URL2 URL3 -o ~/Videos
```

Both `x.com` and `twitter.com` URLs work. Raw tweet ids also work.

## Options

| option                  | description                                              |
| ----------------------- | -------------------------------------------------------- |
| `-o, --output DIR`      | folder to save videos into (default: current directory)  |
| `-F, --list-formats`    | list available formats, don't download                   |
| `-f, --format ID`       | format to download (default: `best`; also `worst`)       |
| `--no-progress`         | hide the progress bar                                    |
| `-q, --quiet`           | only print errors                                        |
| `-V, --version`         | print version                                            |

## How it works

1. Extracts the tweet id from the URL.
2. Fetches tweet metadata from X's public syndication endpoint (no login
   needed). If that returns nothing, it falls back to X's guest-token GraphQL
   API, which handles more cases.
3. Picks the highest-bitrate MP4 variant and streams it to disk.

Note: downloaders are inherently site-specific. The extraction code here is
written for X (formerly Twitter) only - the APIs, token algorithm and response
shapes are X's, and won't apply to other sites. Both X approaches are
implemented so that if one stops working, the other takes over.

No API keys, no cookies, no third-party packages - pure standard library.

## Development

```bash
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS/Linux
pip install -e .
x-dl --help
```

## Disclaimer

For personal use only. Respect X's Terms of Service and content creators'
rights.
