MEDEIA-MACINA

Medeia-Macina is a text-first media manager and plugin runtime for searching, downloading, tagging, archiving, replaying, and moving media through one CLI. It is built around pipeable commands, rich result tables, and row replay so you can move from search to action without leaving the terminal.

The current UX is plugin-first. Older internal names like provider and tool still exist in some code paths and authoring APIs, but the user-facing model is now centered on plugins.

What Medeia-Macina Does

• Search local and remote sources through plugins.
• Browse results as tables and replay rows with @N.
• Chain follow-up actions with |.
• Add or move files into configured backends such as HydrusNetwork.
• Inspect metadata, tags, URLs, and file details from the same CLI.
• Hand media off to MPV for playback, screenshots, and related workflows.
• Load bundled plugins or drop-in plugins from external paths.

How The App Works

The basic interaction loop is:

1. Run a command that returns a table.
2. Use @N to select a row.
3. Let the row replay its plugin-defined action, or pipe it into another command.
4. Use .config any time to inspect or update configuration.

That means rows are not just display data. A row can carry selection arguments or a full replay action. Depending on the plugin and row type, plain @N might open a nested table, download a file, show details, or trigger another plugin-specific workflow.

Plugin System

Plugins are the main integration surface for the app.

• Built-in integrations such as HydrusNetwork, yt-dlp/YouTube, FTP, SCP, Soulseek, Telegram, Internet Archive, OpenLibrary, Bandcamp, and others are treated as plugins.
• Plugins can expose named instances, so one plugin can target multiple endpoints, accounts, or servers via -instance <name>.
• Bundled and external plugins use the same plugins/<name>/ layout.
• External plugin search paths include the repo plugins/ folder, the current working directory plugins/ folder, MM_PLUGIN_PATH, and MEDEIA_PLUGIN_PATH.
• Plugin authoring still uses the current Python base class name PluginCore.base.Provider. That is an implementation detail rather than the preferred user-facing term.

See plugins/README.md for plugin packaging and discovery details.

Configuration

The old interactive TUI config editor has been discontinued.

Use .config from inside the CLI instead:

• .config opens the root configuration table.
• @N drills into a selected section.
• @.. goes back.
• .config plugins jumps straight to the user-facing plugin section.
• Selecting a value row and running .config <value> updates that setting.

This keeps configuration inside the same table-and-selection model as the rest of the app.

Installation From A Git Checkout

Requirements:

• Python 3.9 through 3.13
• Git
• PowerShell on Windows
• mpv recommended for playback workflows

From the repository root, run:

Set-Location C:\path\to\Medios-Macina

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\bootstrap.ps1 -Editable

.\.venv\Scripts\Activate.ps1
mm

Notes:

• The bootstrap script creates .venv, installs the project, and exposes the mm and medeia console commands.
• On Windows, the bootstrap script will try to ensure mpv is available.
• Playwright browser support is installed by default unless you pass -NoPlaywright.
• The repository also ships scripts/bootstrap.py and scripts/bootstrap.sh, but the examples here use PowerShell.

First Run

After launching mm, start with configuration:

.config
.config plugins

If you want the full archive/tag/search workflow, HydrusNetwork is usually the first plugin to configure.

Example Workflows

Browse plugin configuration:

.config
.config plugins

Search a configured plugin instance:

search-file -plugin ftp -instance work "invoice"

Replay a selected row:

@1

Ingest a selected remote result into a configured backend:

@1 | add-file -instance tutorial

Upload a local file through a plugin:

add-file -plugin ftp -instance archive -path C:\Media\report.pdf

The exact meaning of @1 depends on the current table and plugin. For example, one row may open a nested directory table while another row may download or replay a file-specific action.

Core Concepts

• search-file: search a plugin, source, or configured backend and produce a table.
• @N: replay or select row N from the most recent table.
• |: pipe the selected result into the next command.
• add-file: ingest a file into a configured backend or upload through a plugin.
• .config: browse and edit configuration from inside the CLI.
• .mpv: hand media off to the integrated MPV workflow.

Documentation

• docs/tag_template_syntax.md
• plugins/README.md
• docs/plugin_guide.md
• docs/plugin_authoring.md
• docs/ftp_plugin_tutorial.md
• docs/scp_plugin_tutorial.md
• docs/BOOTSTRAP_TROUBLESHOOTING.md

Current Direction

Medeia-Macina is moving toward one canonical plugin model:

• user-facing integrations are described as plugins
• plugin rows carry their own replay actions when needed
• nested tables use the same @N and @.. interaction model across config and plugin workflows
• Hydrus-backed archiving, metadata, and playback flows are treated as part of the same CLI pipeline rather than separate apps