Metadata-Version: 2.4
Name: ytascii-player
Version: 0.3.0
Summary: Play any YouTube video as synced, true-color ASCII art in your terminal.
Author: Your Name
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/ytascii-player
Keywords: ascii,ascii-art,youtube,terminal,cli,video
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: yt-dlp>=2024.1.1
Requires-Dist: opencv-python>=4.8
Requires-Dist: numpy>=1.24
Requires-Dist: imageio-ffmpeg>=0.4.9

# ytascii-player

Play any YouTube video as synced, true-color ASCII art in your terminal.

```
pip install ytascii-player
ytascii "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
ytascii "never gonna give you up rick astley"
```

That's it — no cloning a repo, no copying `.py` files, no `python script.py` syntax,
and **no separate ffmpeg/yt-dlp install**. `pip install` is genuinely all that's needed.
You can paste a video URL **or just type a name/description** — both work.

## Requirements

- **Python 3.8+** — that's it. Everything else is a normal pip dependency:
  `yt-dlp` (used as a Python library, not a CLI tool), `opencv-python`, `numpy`,
  and `imageio-ffmpeg` (ships a real ffmpeg binary *inside* the pip package itself,
  so there's nothing to separately download or add to PATH).

## Usage

```
ytascii "https://www.youtube.com/watch?v=VIDEO_ID"
ytascii "imagine dragons believer"
ytascii "URL or search text" --width 140
ytascii "URL or search text" --mode grayscale
```

You can pass either a YouTube URL, or just a plain video/song name/description -
ytascii detects which one you gave it and searches YouTube automatically for
anything that isn't a link. Multi-word searches need quotes, same as URLs do.

| Flag | Default | Description |
|---|---|---|
| `--width` | `120` | ASCII art width in characters. Higher = more detail, more CPU. |
| `--mode` | `color` | `color` = true 24-bit RGB per character. `grayscale` = classic single-color, faster. |

Press **Ctrl+C** anytime to stop playback. When you search by name, ytascii
prints which video it actually found before downloading - useful if the top
YouTube result wasn't the one you meant (e.g. it grabbed a cover or lyric video).

## Tuning tips

- Maximize your terminal and shrink the font (try 8pt) before running.
- **Windows Terminal** renders far more smoothly than the legacy `conhost` cmd window.
- If playback is choppy, lower `--width` or use `--mode grayscale`.

## Troubleshooting

**`ytascii` : command not recognized, right after installing**
Pip installs the command into a `Scripts` folder that isn't always on your
system's PATH by default — this depends on how Python itself was installed on
your machine. Two options:
1. **Quick workaround, no setup changes:** run `python -m ytascii.cli "URL"` instead —
   this works immediately because it doesn't rely on PATH at all.
2. **Permanent fix:** when you ran the install, pip prints a warning like
   `The script ytascii.exe is installed in 'C:\...\Scripts' which is not on PATH`.
   Copy that exact folder path, then: Win key → search "Environment Variables" →
   *Edit environment variables for your account* → select `Path` → *Edit* → *New* →
   paste the folder → OK. Open a **new** terminal and `ytascii` will work directly.

**`'pip' is not recognized`**
Same PATH issue, one level up. Use `python -m pip install ytascii-player` instead,
which works regardless of PATH.

## Legal note

Only use this on videos you have the right to download — your own uploads,
Creative Commons content, or otherwise permitted use.

## For developers: installing from source

```
git clone <this-repo>
cd ytascii-player
pip install -e .
```

`-e` installs in "editable" mode — code changes apply instantly without reinstalling.

## Publishing (maintainer notes)

```
pip install build twine
python -m build
twine upload dist/*
```
Username is literally `__token__`; password is your PyPI API token from
Account Settings → API tokens. Remember to bump the version number in
`pyproject.toml` and `src/ytascii/__init__.py` before every new upload —
PyPI never allows re-uploading the same version number.
