159 lines
5.7 KiB
Markdown
159 lines
5.7 KiB
Markdown
# 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](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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
.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:
|
|
|
|
```powershell
|
|
.config
|
|
.config plugins
|
|
```
|
|
|
|
Search a configured plugin instance:
|
|
|
|
```powershell
|
|
search-file -plugin ftp -instance work "invoice"
|
|
```
|
|
|
|
Replay a selected row:
|
|
|
|
```powershell
|
|
@1
|
|
```
|
|
|
|
Ingest a selected remote result into a configured backend:
|
|
|
|
```powershell
|
|
@1 | add-file -instance tutorial
|
|
```
|
|
|
|
Upload a local file through a plugin:
|
|
|
|
```powershell
|
|
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](docs/tag_template_syntax.md)
|
|
- [plugins/README.md](plugins/README.md)
|
|
- [docs/plugin_guide.md](docs/plugin_guide.md)
|
|
- [docs/plugin_authoring.md](docs/plugin_authoring.md)
|
|
- [docs/ftp_plugin_tutorial.md](docs/ftp_plugin_tutorial.md)
|
|
- [docs/scp_plugin_tutorial.md](docs/scp_plugin_tutorial.md)
|
|
- [docs/BOOTSTRAP_TROUBLESHOOTING.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
|
|
|
|
|