Medios-Macina/readme.md

# Medios-Macina

Medios-Macina is a CLI media manager and toolkit focused on downloading, tagging, and media storage (audio, video, images, and text) from a variety of providers and sources. It is designed around a compact, pipeable command language ("cmdlets") so complex workflows can be composed simply and repeatably.

## Features
- **Flexible syntax structure:** chain commands with `|` and select options from tables with `@N`.
- **Multiple file stores:** *HYDRUSNETWORK, FOLDER*
- **Provider plugin integration:** *YOUTUBE, OPENLIBRARY/ARCHIVE.ORG, SOULSEEK, LIBGEN, ALLDEBRID, TELEGRAM, BANDCAMP*
- **Module Mixing:** *[Playwright](https://github.com/microsoft/playwright), [yt-dlp](https://github.com/yt-dlp/yt-dlp), [aioslsk](https://github.com/JurgenR/aioslsk), [telethon](https://github.com/LonamiWebs/Telethon),[typer](https://github.com/fastapi/typer)*
- **MPV Manager:** Play audio, video, and even images in a custom designed MPV with trimming, screenshotting, and more built right in! 

## Quick start ⚡

 `docs/BOOTSTRAP.md` and use `scripts/bootstrap.ps1` (Windows) or `scripts/bootstrap.sh` (Linux/macOS) to create a venv and install the project. Alternatively, simply run the opinionated helper: `python ./scripts/setup.py`. By default (no flags), `setup.py` will auto-detect your platform and run the matching bootstrap script in **non-interactive (quiet)** mode so you don't need to run the platform-specific script yourself. The bootstrap scripts also attempt (best-effort) to install `mpv` if it's missing from PATH. Note: the Deno installer can require interactive input on some systems; if the automated Deno install fails, the script will warn and you can install Deno manually by following `docs/BOOTSTRAP.md`.

1. Install Python requirements:

```powershell
python -m pip install -r requirements.txt

# Automated setup (recommended): run the single Python setup script which installs
# all Python dependencies (from requirements.txt) and downloads Playwright browsers.
# Usage:
#  - Default: python ./scripts/setup.py  # installs Chromium only (saves disk)
#  - To install all Playwright engines: python ./scripts/setup.py --browsers all

# Advanced options:
#  - Skip dependency installation: python ./scripts/setup.py --skip-deps
#  - Install only Playwright browsers: python ./scripts/setup.py --playwright-only
#  - Install only specific browsers (saves disk): python ./scripts/setup.py --browsers chromium
#  - Example: install only Chromium browsers: python ./scripts/setup.py --playwright-only --browsers chromium
```
2. Copy or edit `config.conf` and set a required `temp` directory where intermediate files are written. Example:

```ini
temp="C:\\Users\\Admin\\Downloads"

[store=folder]
name="default"
path="C:\\Media Machina"

[store=hydrusnetwork]
NAME="home"
API="..."
URL="http://localhost:45869"

[provider=OpenLibrary]
email="user@example.com"
password="..."
```

3. Start the CLI:

```powershell
cd "C:\location\to\repository\medios-machina\"
python cli.py
```

## Usage overview 🔧
- Pipelines: chain cmdlets with `|`, e.g., `download-media <url> | add-file -storage local`.
  - From your shell you can pass a fully-quoted pipeline so the shell doesn't interpret `|` as a pipe: e.g.
    `mm "download-media <url> | add-file -storage local"`
  - Format selection (non-interactive): When `download-media` shows multiple formats, you can select one non-interactively by re-running the pipeline and specifying the format:
    - Use a format id: `mm "download-media '<url>' -format 243 | add-file -store local"`
    - Or use the listed index (1-based): `mm "download-media '<url>' -query 'format:7' | add-file -store local"`
    Note: The `@N` selection syntax works in the interactive REPL, but shells like PowerShell treat `@` specially — prefer `-query 'format:N'` when running a quoted pipeline from your shell.
- Selections: search cmdlets populate a selectable ResultTable; refer to entries with `@<index>`.
- Tagging & metadata: `add-tag` mutates piped results (temporary path items) or writes to a configured store when `-store` is provided.

## Built-in image viewer 🎞️
- MPV automatically detects still-image files and flips into an image viewer mode while leaving the IPC helper aware via `user-data/mpv/image`.
- Arrow keys, `WASD`, or `h/j/k/l` pan the image (recently tuned to ±0.05 steps), `Shift+arrow` offers finer nudges, `=`/`-` zoom quickly (~45% per press), `+`/`_` zoom slowly, and `0` resets zoom/pan back to default.
- Hit `f` while an image is active to take a screenshot (uses MPV's screenshot pipeline) and get an OSD confirmation.
- When MPV loads a video again, the script restores the regular video shortcuts automatically.

## Common examples 💡

Simple download with metadata (tags and URL registration):
```bash
download-media "https://www.youtube.com/watch?v=dQw4w9WgXcQ" | add-file -storage local | add-url
```

Download a playlist item:
```bash
download-media "https://www.youtube.com/playlist?list=PLxxxxx" -item 2 | add-file -storage local | add-url
```

Take a website screenshot, tag it, and store locally:
```bash
screen-shot "https://example.com/page" | add-tag "title:Example Page,source:web" | add-file -store local
```

OpenLibrary ingestion (book metadata & PDF/ebook handling is automatically enriched when `add-file` detects an OpenLibrary URL):
```bash
add-file "https://openlibrary.org/books/OLxxxxxM/Book_Title" -storage local
```

Search & download flow (select with `@`):
```bash
search-file -provider youtube "my favourite track"
@1
download-media [URL] | add-file -store hydrus
```

## Providers & stores
- **HydrusNetwork**: use for database-backed media storage and advanced tagging (requires running Hydrus client/server).
- **Local folder**: copy files to a configured directory (fast and simple).
- **YouTube / yt-dlp**: robust media downloader for YouTube and many hosts.
- **OpenLibrary / Archive.org**: scripted metadata scraping and optional downloads.
- **Soulseek, LibGen, All-Debrid, Others**: provider support is modular—add or configure providers in `config.conf`.

## Troubleshooting & tips 🛠️
- If a cmdlet complains about an unknown store, ensure the piped item has a valid local `path` or use `-store <name>` to target a configured backend.
- For Playwright screenshots, run `python ./scripts/setup.py` (installs Chromium by default to save download space). To install all engines, run `python ./scripts/setup.py --browsers all`.
- Note: the `screen-shot` cmdlet forces the Playwright **Chromium** engine and will not use Firefox or WebKit.
- To run tests locally after removing `tests/conftest.py`, install the project in editable mode first so tests can import the package: `python -m pip install -e .` or run `python ./scripts/setup.py --install-editable`.
- Deno: The bootstrap scripts will install Deno automatically if it's not already installed (using the official installers). If the installer completes but `deno` is not available in your shell, restart your shell or add `$HOME/.deno/bin` (Windows: `%USERPROFILE%\\.deno\\bin`) to your PATH.

  After installation, restart your shell (or add Deno's bin directory to your PATH) so `deno` is available on the command line.
- Use `--debug` to enable verbose logs when tracking down an error.

## Contributing & docs
- Developer docs are generated under `docs/` and tests live alongside the code; please run the test suite before submitting changes.
- Contributions welcome—open issues or pull requests with clear descriptions and small, focused diffs.

---

If you'd like, I can add a short _Quick Reference_ section listing the most-used cmdlets and flags, or add badges and a table of contents. What would you like me to add next? 🚀