128 lines
7.3 KiB
Markdown
128 lines
7.3 KiB
Markdown
# 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 ⚡
|
|
|
|
Prefer an automated setup? See `docs/BOOTSTRAP.md` and use `scripts/bootstrap.ps1` (Windows) or `scripts/bootstrap.sh` (Linux/macOS) to create a venv and install the project. Alternatively, run the opinionated helper: `python ./scripts/setup.py` which creates a `.venv` at the repo root, installs dependencies into it, writes convenient `mm` launchers in the project root, and installs a global `mm` shim into your user PATH so you can run `mm` from anywhere.
|
|
|
|
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? 🚀 |