jj

readme.md

@@ -1,18 +1,30 @@
 # Medios-Macina
-- Audio
-- Video
-- Image
-- Text
 
-### Configuration
+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.
 
-The default config format is `config.conf`.
+## 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.
 
-- Required: `temp` (where temporary/intermediate files are written)
-- Optional: any number of stores and provider credentials
-- Modular: you can add extra `.conf` fragments in `config.d\*.conf` (they will be merged)
+## Quick start ⚡
+1. Install Python requirements:
 
-Example `config.conf`:
+```powershell
+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:
+python ./scripts/setup.py
+
+# Advanced options:
+#  - Skip dependency installation: python ./scripts/setup.py --skip-deps
+#  - Install only Playwright browsers: python ./scripts/setup.py --playwright-only
+```
+2. Copy or edit `config.conf` and set a required `temp` directory where intermediate files are written. Example:
 
 ```ini
 temp="C:\\Users\\Admin\\Downloads"
@@ -31,70 +43,63 @@ email="user@example.com"
 password="..."
 ```
 
-### File Store
-- HydrusNetwork https://github.com/hydrusnetwork/hydrus
-- Local drive (C://mylibrary/path)   
+3. Start the CLI:
 
-### File Providers
-- Youtube
-- Openlibrary/Archive.org (free account needed)
-- Soulseek
-- Gog-Games (limited without paid API)
-- Libgen
-- All-Debrid https://alldebrid.com/
-
-### Features
-- Full MPV integration https://github.com/mpv-player/mpv 
-- Database file management
-- API/CLI exclusive 
-- Plug and play stores and add-ons
-- YT-DLP integration
-- CMDLET easy syntax
-- CLI auto-complete
-
-Install what you need and want, after you have the requirements.txt installed as well you will need to open terminal at the repository download location and run the cli file like .
-
-
-#### Quick
-
-```shell
+```powershell
 cd "C:\location\to\repository\medios-machina\"
 python cli.py
 ```
-Adding your first file
-```python
-.pipe -list  # List MPV current playing/list
-.pipe -save  # Save current MPV playlist to local library
-.pipe -load  # List saved playlists; use @N to load one
-.pipe "https://www.youtube.com/watch?v=_23dFb50Z2Y"  # Add URL to current playlist
-```
 
-Example pipelines:
+## 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.
 
-1. **Simple download with metadata (tags and URL registration)**:
-```
+## Common examples 💡
+
+Simple download with metadata (tags and URL registration):
+```bash
 download-media "https://www.youtube.com/watch?v=dQw4w9WgXcQ" | add-file -storage local | add-url
 ```
 
-2. **Download playlist item with tags**:
-```
+Download a playlist item:
+```bash
 download-media "https://www.youtube.com/playlist?list=PLxxxxx" -item 2 | add-file -storage local | add-url
 ```
 
-3. **Download with merge (e.g., Bandcamp albums)**:
-```
-download-data "https://altrusiangrace.bandcamp.com/album/ancient-egyptian-legends-full-audiobook" | merge-file | add-file -storage local | add-url
+Take a website screenshot, tag it, and store locally:
+```bash
+screen-shot "https://example.com/page" | add-tag "title:Example Page,source:web" | add-file -store local
 ```
 
-4. **Download direct file (PDF, document)**:
-```
-download-file "https://example.com/file.pdf" | add-file -storage local | add-url
+OpenLibrary ingestion (book metadata & PDF/ebook handling is automatically enriched when `add-file` detects an OpenLibrary URL):
+```bash
+add-file "https://openlibrary.org/books/OLxxxxxM/Book_Title" -storage local
 ```
 
-Search examples:
+Search & download flow (select with `@`):
+```bash
+search-file -provider youtube "my favourite track"
+@1
+download-media [URL] | add-file -store hydrus
+```
 
-1. search-file -provider youtube "something in the way"
+## 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`.
 
-2. @1
+## 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 `playwright install` after installing the package to download browser binaries.
+- Use `--debug` to enable verbose logs when tracking down an error.
 
-3. download-media [URL] | add-file -storage local | add-url
+## 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? 🚀