Medios-Macina

Medios-Macina is a CLI-first media ingestion and management toolkit focused on reliably downloading, tagging, and storing media (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.

Highlights ✅

• Flexible pipeline-based CLI: chain cmdlets with | and use saved selections with @N.
• Multi-store support: HydrusNetwork, local folders, and provider-backed stores.
• Provider integrations: YouTube, OpenLibrary/Archive.org, Soulseek, LibGen, AllDebrid, and more.
• Utility cmdlets: screenshots (Playwright), metadata extraction, merging, and automated tagging.
• MPV-friendly: integrate with MPV playback and playlists for quick ingestion.

Quick start ⚡

1. 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

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

3. 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.
• 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.

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: this setup script now installs Deno by default. To opt out, run python ./scripts/setup.py --no-deno. You can still pin a version: python ./scripts/setup.py --deno-version v1.34.3.
• 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? 🚀