Medeia-Macina

This repository now keeps its detailed guide inside scripts/README.md to keep the root folder lean. See that file for installation, usage, and contributor information.# 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, INTERNETARCHIVE, SOULSEEK, LIBGEN, ALLDEBRID, TELEGRAM, BANDCAMP
• Module Mixing: Playwright, yt-dlp, typer
• Optional stacks: Telethon (Telegram), aioslsk (Soulseek), and the FlorenceVision tooling install automatically when you configure the corresponding provider/tool blocks.
• MPV Manager: Play audio, video, and even images in a custom designed MPV with trimming, screenshotting, and more built right in!

installation ⚡

GIT CLONE https://code.glowers.club/goyimnose/Medios-Macina

1. run python scripts\bootstrap.py

   • When run interactively (a normal terminal), bootstrap.py will show a short menu to Install or Uninstall the project. For non-interactive runs use flags such as --no-playwright, --uninstall, or -y to assume yes for confirmations.

     Note: If you run --uninstall while the local .venv is activated, the uninstaller will try to re-run the uninstall using a Python interpreter outside the venv so files can be removed safely (this is helpful on Windows). If no suitable interpreter can be found, deactivate the venv (deactivate) and re-run the uninstall.

   Optional providers/tools bring their own dependencies instead of shipping as part of the base install; just configure [provider=telegram], [provider=soulseek], or [tool=florencevision] and the CLI will install the required packages on startup.

2. rename config.conf.remove to config.conf the store=folder path should be empty folder with no other files in it.

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

[store=folder]
name="default"
path="C:\Users\Public\Documents\library"

3. Start the CLI by simply running "mm" in shell or run python cli.py

CLICK FOR GUIDED TUTORIAL

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 '' -query 'format:243' -path 'C://path' "
    • Or use the listed index (1-based): mm "download-media '<url>' -query 'format:7' " Note: The @Nselection 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
• 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 

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" -path "c://"

OpenLibrary ingestion (book metadata & PDF/ebook handling is automatically enriched when add-file detects an OpenLibrary URL):

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

Search your library:

search-file "ext:mp3"

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: book metadata, borrowing, and Archive.org downloads.
• Internet Archive: search/download/upload via the internetarchive module.
• Soulseek, LibGen, All-Debrid, Others: provider support is modular—add or configure providers in config.conf.

Troubleshooting & tips 🛠️

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.