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, yt-dlp, aioslsk, telethon,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.

Install Python requirements:

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

Copy or edit config.conf and set a required temp directory where intermediate files are written. Example:

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="..."

Start the CLI:

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):

download-media "https://www.youtube.com/watch?v=dQw4w9WgXcQ" | add-file -storage local | add-url

Download a playlist item:

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:

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):

add-file "https://openlibrary.org/books/OLxxxxxM/Book_Title" -storage local

Search & download flow (select with @):

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? 🚀

7.6 KiB Raw Blame History