alchemux 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. alchemux-0.1.2/LICENSE +8 -0
  2. alchemux-0.1.2/PKG-INFO +242 -0
  3. alchemux-0.1.2/README.md +211 -0
  4. alchemux-0.1.2/backend/alchemux.egg-info/PKG-INFO +242 -0
  5. alchemux-0.1.2/backend/alchemux.egg-info/SOURCES.txt +73 -0
  6. alchemux-0.1.2/backend/alchemux.egg-info/dependency_links.txt +1 -0
  7. alchemux-0.1.2/backend/alchemux.egg-info/entry_points.txt +3 -0
  8. alchemux-0.1.2/backend/alchemux.egg-info/requires.txt +15 -0
  9. alchemux-0.1.2/backend/alchemux.egg-info/top_level.txt +1 -0
  10. alchemux-0.1.2/backend/app/__init__.py +1 -0
  11. alchemux-0.1.2/backend/app/cli/__init__.py +7 -0
  12. alchemux-0.1.2/backend/app/cli/app.py +311 -0
  13. alchemux-0.1.2/backend/app/cli/argv_normalize.py +121 -0
  14. alchemux-0.1.2/backend/app/cli/batch_parsing.py +80 -0
  15. alchemux-0.1.2/backend/app/cli/commands/__init__.py +4 -0
  16. alchemux-0.1.2/backend/app/cli/commands/accept_eula.py +38 -0
  17. alchemux-0.1.2/backend/app/cli/commands/audio_format.py +116 -0
  18. alchemux-0.1.2/backend/app/cli/commands/batch.py +367 -0
  19. alchemux-0.1.2/backend/app/cli/commands/config.py +603 -0
  20. alchemux-0.1.2/backend/app/cli/commands/debug.py +62 -0
  21. alchemux-0.1.2/backend/app/cli/commands/distill.py +569 -0
  22. alchemux-0.1.2/backend/app/cli/commands/doctor.py +306 -0
  23. alchemux-0.1.2/backend/app/cli/commands/inspect.py +66 -0
  24. alchemux-0.1.2/backend/app/cli/commands/invoke.py +81 -0
  25. alchemux-0.1.2/backend/app/cli/commands/mux.py +57 -0
  26. alchemux-0.1.2/backend/app/cli/commands/plain.py +53 -0
  27. alchemux-0.1.2/backend/app/cli/commands/save_default.py +105 -0
  28. alchemux-0.1.2/backend/app/cli/commands/seal.py +50 -0
  29. alchemux-0.1.2/backend/app/cli/commands/setup.py +142 -0
  30. alchemux-0.1.2/backend/app/cli/commands/storage.py +283 -0
  31. alchemux-0.1.2/backend/app/cli/commands/update.py +276 -0
  32. alchemux-0.1.2/backend/app/cli/commands/verbose.py +61 -0
  33. alchemux-0.1.2/backend/app/cli/commands/video_format.py +133 -0
  34. alchemux-0.1.2/backend/app/cli/output.py +658 -0
  35. alchemux-0.1.2/backend/app/cli/prompts.py +260 -0
  36. alchemux-0.1.2/backend/app/cli/selectors.py +281 -0
  37. alchemux-0.1.2/backend/app/cli/url_input.py +270 -0
  38. alchemux-0.1.2/backend/app/core/__init__.py +1 -0
  39. alchemux-0.1.2/backend/app/core/config_manager.py +839 -0
  40. alchemux-0.1.2/backend/app/core/config_wizard.py +598 -0
  41. alchemux-0.1.2/backend/app/core/downloader.py +579 -0
  42. alchemux-0.1.2/backend/app/core/eula.py +156 -0
  43. alchemux-0.1.2/backend/app/core/logger.py +302 -0
  44. alchemux-0.1.2/backend/app/core/setup_wizard.py +829 -0
  45. alchemux-0.1.2/backend/app/core/toml_config.py +193 -0
  46. alchemux-0.1.2/backend/app/core/tracebacks.py +98 -0
  47. alchemux-0.1.2/backend/app/entrypoint.py +285 -0
  48. alchemux-0.1.2/backend/app/main.py +20 -0
  49. alchemux-0.1.2/backend/app/services/__init__.py +1 -0
  50. alchemux-0.1.2/backend/app/services/gcp_upload.py +221 -0
  51. alchemux-0.1.2/backend/app/services/s3_upload.py +216 -0
  52. alchemux-0.1.2/backend/app/templates/config.toml.example +100 -0
  53. alchemux-0.1.2/backend/app/templates/env.example +38 -0
  54. alchemux-0.1.2/backend/app/tests/__init__.py +1 -0
  55. alchemux-0.1.2/backend/app/tests/test_batch_command.py +56 -0
  56. alchemux-0.1.2/backend/app/tests/test_batch_file_discovery.py +70 -0
  57. alchemux-0.1.2/backend/app/tests/test_batch_parsing.py +88 -0
  58. alchemux-0.1.2/backend/app/tests/test_batch_playlist_expansion.py +64 -0
  59. alchemux-0.1.2/backend/app/tests/test_cli_argv_normalize.py +98 -0
  60. alchemux-0.1.2/backend/app/tests/test_cli_clipboard_input.py +85 -0
  61. alchemux-0.1.2/backend/app/tests/test_cli_config_smoke.py +108 -0
  62. alchemux-0.1.2/backend/app/tests/test_cli_interactive_input.py +160 -0
  63. alchemux-0.1.2/backend/app/tests/test_config_doctor_repair.py +188 -0
  64. alchemux-0.1.2/backend/app/tests/test_config_manager.py +262 -0
  65. alchemux-0.1.2/backend/app/tests/test_downloader_path_resolution.py +54 -0
  66. alchemux-0.1.2/backend/app/tests/test_ephemeral_config.py +49 -0
  67. alchemux-0.1.2/backend/app/tests/test_update_command.py +116 -0
  68. alchemux-0.1.2/backend/app/tests/test_ux_polish.py +188 -0
  69. alchemux-0.1.2/backend/app/tests/test_video_enabled_gating.py +132 -0
  70. alchemux-0.1.2/backend/app/utils/__init__.py +1 -0
  71. alchemux-0.1.2/backend/app/utils/deps.py +211 -0
  72. alchemux-0.1.2/backend/app/utils/file_utils.py +354 -0
  73. alchemux-0.1.2/backend/app/utils/metadata.py +227 -0
  74. alchemux-0.1.2/pyproject.toml +67 -0
  75. alchemux-0.1.2/setup.cfg +4 -0
alchemux-0.1.2/LICENSE ADDED
@@ -0,0 +1,8 @@
1
+ LICENSE
2
+ ================================================================================
3
+
4
+ This project is licensed under the GNU Affero General Public License v3.0
5
+ (AGPL-3.0).
6
+
7
+ Full license text:
8
+ https://www.gnu.org/licenses/agpl-3.0.en.html
alchemux-0.1.2/PKG-INFO ADDED
@@ -0,0 +1,242 @@
1
+ Metadata-Version: 2.4
2
+ Name: alchemux
3
+ Version: 0.1.2
4
+ Summary: CLI wrapper for yt-dlp & FFmpeg with cloud upload optionality
5
+ License: AGPL-3.0
6
+ Classifier: Development Status :: 4 - Beta
7
+ Classifier: Environment :: Console
8
+ Classifier: Intended Audience :: End Users/Desktop
9
+ Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
14
+ Requires-Python: >=3.12
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: yt-dlp>=2024.1.0
18
+ Requires-Dist: python-dotenv>=1.0.0
19
+ Requires-Dist: mutagen>=1.47.0
20
+ Requires-Dist: typer>=0.12.0
21
+ Requires-Dist: rich>=13.0.0
22
+ Requires-Dist: InquirerPy>=0.3.4
23
+ Requires-Dist: pyperclip>=1.8.0
24
+ Requires-Dist: platformdirs>=4.0.0
25
+ Requires-Dist: tomli>=2.0.0; python_version < "3.11"
26
+ Requires-Dist: tomli-w>=1.0.0
27
+ Requires-Dist: tomlkit>=0.12.0
28
+ Requires-Dist: google-cloud-storage>=2.10.0
29
+ Requires-Dist: boto3>=1.28.0
30
+ Dynamic: license-file
31
+
32
+ <div align="center">
33
+
34
+ # Alchemux
35
+
36
+ **Magically intuitive CLI for yt-dlp & FFmpeg** — download, convert, and optionally upload to **S3** or **GCP**.
37
+
38
+ *Interactive terminal alchemy for YouTube and 1,000+ media sources.*
39
+
40
+ [![Star on GitHub](https://img.shields.io/badge/Star-on_GitHub-blue?logo=github)](https://github.com/bmurrtech/alchemux)
41
+ [![PyPI version](https://img.shields.io/pypi/v/alchemux?label=pypi)](https://pypi.org/project/alchemux/)
42
+ [![PyPI downloads](https://img.shields.io/pypi/dm/alchemux?label=downloads&color=success)](https://pypi.org/project/alchemux/)
43
+ [![CI](https://img.shields.io/github/actions/workflow/status/bmurrtech/alchemux/ci.yml?branch=main&logo=github&label=CI)](https://github.com/bmurrtech/alchemux/actions/workflows/ci.yml?query=branch%3Amain)
44
+ [![Latest Release](https://img.shields.io/github/v/release/bmurrtech/alchemux?include_prereleases&label=release&logo=github)](https://github.com/bmurrtech/alchemux/releases)
45
+ [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue.svg)](https://docs.astral.sh/uv/)
46
+ [![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
47
+ [![uv](https://img.shields.io/badge/distributed_with-uv-DE5FE9.svg)](https://docs.astral.sh/uv/)
48
+ [![License: AGPL v3](https://img.shields.io/badge/license-GNU%20AGPLv3-blue.svg)](LICENSE)
49
+ [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?logo=ko-fi)](https://ko-fi.com/bmurrtech)
50
+ [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-FFDD00?logo=buymeacoffee&logoColor=black)](https://www.buymeacoffee.com/bmurrtech)
51
+
52
+ <p align="center">
53
+ <img src="https://i.imgur.com/coG2REg.png" width="700" alt="Alchemux CLI transmuting media">
54
+ <br><br>
55
+ <img src="https://i.imgur.com/iDFjVCw.png" width="700" alt="Alchemux usage example">
56
+ </p>
57
+
58
+ </div>
59
+
60
+ ## About
61
+
62
+ Alchemux is a **terminal-first** media CLI built on [yt-dlp](https://github.com/yt-dlp/yt-dlp) and **system FFmpeg**. It wraps complex download and conversion workflows in an interactive wizard, batch mode, optional cloud upload, and arcane (or plain) terminal output.
63
+
64
+ - **Distribution**: [PyPI](https://pypi.org/project/alchemux/) — install with [uv](https://docs.astral.sh/uv/) (`uv tool install` / `uvx`)
65
+ - **Platforms**: macOS, Linux, Windows (shell + Python 3.12+)
66
+ - **Config**: Per-user TOML via `alchemux setup` — no manual file editing required
67
+ - **Status**: Pre-release — bugs and limitations are expected; see [docs/known-issues.md](docs/known-issues.md)
68
+
69
+ ## Features
70
+
71
+ - 🎵 **Download & Convert Media**: Extract audio or video from YouTube, Facebook, and other [yt-dlp supported sources](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md)
72
+ - 🧙‍♂️ **Interactive Simplicity**: Delightfully easy terminal UI—just run and follow prompts; configure everything in seconds (including cloud storage and presets) interactively
73
+ - 📋 **Batch Processing**: Process many URLs from a YouTube playlist, TXT/CSV files, or pasted lists of URLs with automatic rate-limit mitigation logic built-in. See [commands.md](docs/commands.md) for batch mode details
74
+ - 🏷️ **Metadata Embedding**: Automatically embeds source URLs and metadata into media files
75
+ - ☁️ **Cloud Storage**: Upload media to **S3** and **GCP buckets** after interactive setup ([commands.md](docs/commands.md))
76
+ - 🎚️ **Multiple Formats**: Audio (MP3, AAC, FLAC, Opus, WAV, etc.) and video (MP4, MKV, WebM, etc.)
77
+ - 🤖 **AI Agent Support**: CLI guidance for agents like [OpenClaw](https://openclaw.ai), [Agent Zero](https://github.com/agent0ai/agent-zero), and Claude Skills — see [backend/AGENTS.md](backend/AGENTS.md)
78
+ - 🛠️ **`config` Command**: Interactive wizard for formats, cloud credentials, download folder, batch defaults, and more
79
+ - 🩺 **`doctor` Command**: Diagnose cloud misconfigurations, missing FFmpeg, permissions, and common failures
80
+ - ✨ **Arcane Interface**: Optional stylized output (disable with `arcane_terms = "false"` or during setup)
81
+ - 🔄 **`update` Command**: Refresh the bundled yt-dlp dependency from the community release channel
82
+
83
+ Full command reference: [docs/commands.md](docs/commands.md).
84
+
85
+ ## Quick Start
86
+
87
+ ### Prerequisites
88
+
89
+ - **Shell**: Terminal (macOS/Linux) or PowerShell (Windows)
90
+ - **uv**: [Astral’s uv](https://docs.astral.sh/uv/) — one-time install below
91
+ - **FFmpeg**: Required (`ffmpeg` + `ffprobe` on PATH) — [docs/install.md § Install FFmpeg](docs/install.md#2-install-ffmpeg-required)
92
+
93
+ ### Install from PyPI (recommended)
94
+
95
+ Installing with **uv** avoids macOS Gatekeeper and Windows SmartScreen prompts that often affect downloaded executables.
96
+
97
+ #### 1) Install uv (one-time)
98
+
99
+ **macOS/Linux:**
100
+
101
+ ```bash
102
+ curl -LsSf https://astral.sh/uv/install.sh | sh
103
+ ```
104
+
105
+ **Windows (PowerShell):**
106
+
107
+ ```powershell
108
+ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
109
+ ```
110
+
111
+ Verify: `uv --version`
112
+
113
+ #### 2) Install as a persistent CLI tool
114
+
115
+ ```bash
116
+ uv tool install alchemux
117
+ alchemux setup
118
+ alchemux "https://youtu.be/…"
119
+ ```
120
+
121
+ `amx` is a short alias for the same CLI (`amx "https://…"`).
122
+
123
+ > **Want to try without installing?**
124
+ >
125
+ > ```bash
126
+ > uvx alchemux --help
127
+ > uvx alchemux "https://youtu.be/…"
128
+ > ```
129
+
130
+ #### 3) Upgrade / uninstall
131
+
132
+ ```bash
133
+ uv tool upgrade alchemux
134
+ uv tool uninstall alchemux
135
+ ```
136
+
137
+ ### Run from source (development)
138
+
139
+ For unreleased or experimental features:
140
+
141
+ ```bash
142
+ git clone https://github.com/bmurrtech/alchemux.git
143
+ cd alchemux
144
+ uv pip install -e .
145
+ uv run alchemux --help
146
+ uv run alchemux setup
147
+ ```
148
+
149
+ See [docs/install.md](docs/install.md) for platform-specific FFmpeg and config paths.
150
+
151
+ ## Arcane terms
152
+
153
+ Alchemux can use arcane-themed wording (transmute, distill, seal, etc.). Prefer plain terms? Set `arcane_terms = "false"` in `config.toml` or choose technical mode during `alchemux setup`. Legend: [docs/legend.md](docs/legend.md).
154
+
155
+ ## Known issues
156
+
157
+ Alchemux is pre-release. Documented limitations, workarounds, and what to check before filing a report: **[docs/known-issues.md](docs/known-issues.md)**.
158
+
159
+ ## Troubleshooting
160
+
161
+ ```bash
162
+ alchemux -h
163
+ amx -h # available after `uv tool install alchemux`
164
+ alchemux doctor
165
+ ```
166
+
167
+ | Problem | Solution |
168
+ |---------|----------|
169
+ | Config not found | Run `alchemux setup` or `alchemux doctor` — paths in [docs/install.md](docs/install.md) |
170
+ | Downloads fail | Try audio-only or `--flac`; run `alchemux update`; see [known-issues.md](docs/known-issues.md) (KI-002, KI-003) |
171
+ | `ffmpeg not found` | Install system FFmpeg (`brew install ffmpeg`, `apt install ffmpeg`, etc.) — [docs/install.md](docs/install.md) |
172
+
173
+ ## Contributing
174
+
175
+ Bug reports, feature requests, and feedback are welcome via **[GitHub Issues](https://github.com/bmurrtech/alchemux/issues/new/choose)**. Please read **[docs/known-issues.md](docs/known-issues.md)** first.
176
+
177
+ Maintainers: local tooling, tests, and CI — **[docs/contributors.md](docs/contributors.md)**. Release process — **[docs/release.md](docs/release.md)**.
178
+
179
+ ## Support open source
180
+
181
+ If Alchemux saves you time, consider:
182
+
183
+ - ⭐ **Starring the repo** — [![Star on GitHub](https://img.shields.io/badge/Star-on_GitHub-blue?logo=github)](https://github.com/bmurrtech/alchemux)
184
+ - 🐛 **[Open a GitHub Issue](https://github.com/bmurrtech/alchemux/issues/new/choose)** — bugs, ideas, and feedback
185
+ - 📣 **Sharing** with others who download or archive media from the terminal
186
+ - ☕ **[Buy Me a Coffee](https://www.buymeacoffee.com/bmurrtech)** or **[Ko-fi](https://ko-fi.com/bmurrtech)**
187
+
188
+ <p align="center">
189
+ <a href="https://www.buymeacoffee.com/bmurrtech" target="_blank" rel="noopener">
190
+ <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support%20the%20project-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black" alt="Buy Me a Coffee">
191
+ </a>
192
+ <a href="https://ko-fi.com/bmurrtech" target="_blank" rel="noopener">
193
+ <img src="https://img.shields.io/badge/Ko--fi-Support%20the%20project-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white" alt="Ko-fi">
194
+ </a>
195
+ </p>
196
+
197
+ ## Acknowledgements
198
+
199
+ - **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — core downloader
200
+ - **[FFmpeg](https://ffmpeg.org/)** — audio/video conversion (system install)
201
+ - **[uv](https://docs.astral.sh/uv/)** — install and run via `uv tool install` / `uvx`
202
+ - **[prek](https://github.com/j178/prek)** — pre-commit hooks in CI and locally
203
+ - **[PyPI](https://pypi.org/)** — package distribution
204
+ - **[Typer](https://typer.tiangolo.com/)**, **[Rich](https://github.com/Textualize/rich)**, **[InquirerPy](https://github.com/kazhala/InquirerPy)** — CLI UX
205
+ - **[pyperclip](https://github.com/pyperclip/pyperclip)**, **[mutagen](https://github.com/quodlibet/mutagen)**, **[python-dotenv](https://github.com/theskumar/python-dotenv)** — clipboard, metadata, env helpers
206
+
207
+ ## License
208
+
209
+ [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0.html)
210
+
211
+ This repository is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE). The badge links to the official license text; the [`LICENSE`](LICENSE) file in this repo is the binding copy.
212
+
213
+ ### License permissions and restrictions
214
+
215
+ *Keeping open-source open.*
216
+
217
+ | Use case | Permitted | Notes / conditions |
218
+ |----------|-----------|-------------------|
219
+ | Private / internal use | ✅ | No obligation to publish changes if you do not distribute or offer the software as a network service to others. |
220
+ | Modify for own private use | ✅ | Obligations attach when you distribute or run modified code as a networked service for users. |
221
+ | Share / distribute (unmodified) | ✅ | Include AGPL license and corresponding source (or compliant written offer). |
222
+ | Distribute with modifications | ✅ | Modified source must be available under AGPL-3.0 to recipients. |
223
+ | Provide as SaaS / network service | ✅ | Users interacting with your modified version over a network must be able to obtain complete corresponding source. |
224
+ | Closed / proprietary redistribution | ❌ | Public distribution or SaaS without corresponding source under AGPL is not allowed. |
225
+ | Restricting source access for users you serve | ❌ | Network users must be able to get complete corresponding source as AGPL defines. |
226
+ | Sublicensing under more restrictive terms | ❌ | AGPL terms must flow through. |
227
+
228
+ ### Commercial / proprietary licensing
229
+
230
+ Need use **without** AGPL copyleft (closed-source distribution, SaaS without source-offer obligations, etc.)? **Commercial licenses may be available.** Open a [GitHub Issue](https://github.com/bmurrtech/alchemux/issues/new/choose) to discuss licensing and pricing.
231
+
232
+ ---
233
+
234
+ ## Disclaimer
235
+
236
+ This software is provided **as-is**, without warranty of any kind. The author(s) are **not liable** for damages or losses from use of this project, including data loss, failed downloads, or cloud storage misconfiguration.
237
+
238
+ By using Alchemux you accept responsibility for:
239
+
240
+ - Complying with this license and the **terms of service** of sites you download from (e.g. YouTube)
241
+ - Ensuring **yt-dlp**, **FFmpeg**, and cloud provider usage comply with their respective licenses and policies
242
+ - Securing your own credentials for S3/GCP and local config files
alchemux-0.1.2/README.md ADDED
@@ -0,0 +1,211 @@
1
+ <div align="center">
2
+
3
+ # Alchemux
4
+
5
+ **Magically intuitive CLI for yt-dlp & FFmpeg** — download, convert, and optionally upload to **S3** or **GCP**.
6
+
7
+ *Interactive terminal alchemy for YouTube and 1,000+ media sources.*
8
+
9
+ [![Star on GitHub](https://img.shields.io/badge/Star-on_GitHub-blue?logo=github)](https://github.com/bmurrtech/alchemux)
10
+ [![PyPI version](https://img.shields.io/pypi/v/alchemux?label=pypi)](https://pypi.org/project/alchemux/)
11
+ [![PyPI downloads](https://img.shields.io/pypi/dm/alchemux?label=downloads&color=success)](https://pypi.org/project/alchemux/)
12
+ [![CI](https://img.shields.io/github/actions/workflow/status/bmurrtech/alchemux/ci.yml?branch=main&logo=github&label=CI)](https://github.com/bmurrtech/alchemux/actions/workflows/ci.yml?query=branch%3Amain)
13
+ [![Latest Release](https://img.shields.io/github/v/release/bmurrtech/alchemux?include_prereleases&label=release&logo=github)](https://github.com/bmurrtech/alchemux/releases)
14
+ [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue.svg)](https://docs.astral.sh/uv/)
15
+ [![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
16
+ [![uv](https://img.shields.io/badge/distributed_with-uv-DE5FE9.svg)](https://docs.astral.sh/uv/)
17
+ [![License: AGPL v3](https://img.shields.io/badge/license-GNU%20AGPLv3-blue.svg)](LICENSE)
18
+ [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?logo=ko-fi)](https://ko-fi.com/bmurrtech)
19
+ [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-FFDD00?logo=buymeacoffee&logoColor=black)](https://www.buymeacoffee.com/bmurrtech)
20
+
21
+ <p align="center">
22
+ <img src="https://i.imgur.com/coG2REg.png" width="700" alt="Alchemux CLI transmuting media">
23
+ <br><br>
24
+ <img src="https://i.imgur.com/iDFjVCw.png" width="700" alt="Alchemux usage example">
25
+ </p>
26
+
27
+ </div>
28
+
29
+ ## About
30
+
31
+ Alchemux is a **terminal-first** media CLI built on [yt-dlp](https://github.com/yt-dlp/yt-dlp) and **system FFmpeg**. It wraps complex download and conversion workflows in an interactive wizard, batch mode, optional cloud upload, and arcane (or plain) terminal output.
32
+
33
+ - **Distribution**: [PyPI](https://pypi.org/project/alchemux/) — install with [uv](https://docs.astral.sh/uv/) (`uv tool install` / `uvx`)
34
+ - **Platforms**: macOS, Linux, Windows (shell + Python 3.12+)
35
+ - **Config**: Per-user TOML via `alchemux setup` — no manual file editing required
36
+ - **Status**: Pre-release — bugs and limitations are expected; see [docs/known-issues.md](docs/known-issues.md)
37
+
38
+ ## Features
39
+
40
+ - 🎵 **Download & Convert Media**: Extract audio or video from YouTube, Facebook, and other [yt-dlp supported sources](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md)
41
+ - 🧙‍♂️ **Interactive Simplicity**: Delightfully easy terminal UI—just run and follow prompts; configure everything in seconds (including cloud storage and presets) interactively
42
+ - 📋 **Batch Processing**: Process many URLs from a YouTube playlist, TXT/CSV files, or pasted lists of URLs with automatic rate-limit mitigation logic built-in. See [commands.md](docs/commands.md) for batch mode details
43
+ - 🏷️ **Metadata Embedding**: Automatically embeds source URLs and metadata into media files
44
+ - ☁️ **Cloud Storage**: Upload media to **S3** and **GCP buckets** after interactive setup ([commands.md](docs/commands.md))
45
+ - 🎚️ **Multiple Formats**: Audio (MP3, AAC, FLAC, Opus, WAV, etc.) and video (MP4, MKV, WebM, etc.)
46
+ - 🤖 **AI Agent Support**: CLI guidance for agents like [OpenClaw](https://openclaw.ai), [Agent Zero](https://github.com/agent0ai/agent-zero), and Claude Skills — see [backend/AGENTS.md](backend/AGENTS.md)
47
+ - 🛠️ **`config` Command**: Interactive wizard for formats, cloud credentials, download folder, batch defaults, and more
48
+ - 🩺 **`doctor` Command**: Diagnose cloud misconfigurations, missing FFmpeg, permissions, and common failures
49
+ - ✨ **Arcane Interface**: Optional stylized output (disable with `arcane_terms = "false"` or during setup)
50
+ - 🔄 **`update` Command**: Refresh the bundled yt-dlp dependency from the community release channel
51
+
52
+ Full command reference: [docs/commands.md](docs/commands.md).
53
+
54
+ ## Quick Start
55
+
56
+ ### Prerequisites
57
+
58
+ - **Shell**: Terminal (macOS/Linux) or PowerShell (Windows)
59
+ - **uv**: [Astral’s uv](https://docs.astral.sh/uv/) — one-time install below
60
+ - **FFmpeg**: Required (`ffmpeg` + `ffprobe` on PATH) — [docs/install.md § Install FFmpeg](docs/install.md#2-install-ffmpeg-required)
61
+
62
+ ### Install from PyPI (recommended)
63
+
64
+ Installing with **uv** avoids macOS Gatekeeper and Windows SmartScreen prompts that often affect downloaded executables.
65
+
66
+ #### 1) Install uv (one-time)
67
+
68
+ **macOS/Linux:**
69
+
70
+ ```bash
71
+ curl -LsSf https://astral.sh/uv/install.sh | sh
72
+ ```
73
+
74
+ **Windows (PowerShell):**
75
+
76
+ ```powershell
77
+ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
78
+ ```
79
+
80
+ Verify: `uv --version`
81
+
82
+ #### 2) Install as a persistent CLI tool
83
+
84
+ ```bash
85
+ uv tool install alchemux
86
+ alchemux setup
87
+ alchemux "https://youtu.be/…"
88
+ ```
89
+
90
+ `amx` is a short alias for the same CLI (`amx "https://…"`).
91
+
92
+ > **Want to try without installing?**
93
+ >
94
+ > ```bash
95
+ > uvx alchemux --help
96
+ > uvx alchemux "https://youtu.be/…"
97
+ > ```
98
+
99
+ #### 3) Upgrade / uninstall
100
+
101
+ ```bash
102
+ uv tool upgrade alchemux
103
+ uv tool uninstall alchemux
104
+ ```
105
+
106
+ ### Run from source (development)
107
+
108
+ For unreleased or experimental features:
109
+
110
+ ```bash
111
+ git clone https://github.com/bmurrtech/alchemux.git
112
+ cd alchemux
113
+ uv pip install -e .
114
+ uv run alchemux --help
115
+ uv run alchemux setup
116
+ ```
117
+
118
+ See [docs/install.md](docs/install.md) for platform-specific FFmpeg and config paths.
119
+
120
+ ## Arcane terms
121
+
122
+ Alchemux can use arcane-themed wording (transmute, distill, seal, etc.). Prefer plain terms? Set `arcane_terms = "false"` in `config.toml` or choose technical mode during `alchemux setup`. Legend: [docs/legend.md](docs/legend.md).
123
+
124
+ ## Known issues
125
+
126
+ Alchemux is pre-release. Documented limitations, workarounds, and what to check before filing a report: **[docs/known-issues.md](docs/known-issues.md)**.
127
+
128
+ ## Troubleshooting
129
+
130
+ ```bash
131
+ alchemux -h
132
+ amx -h # available after `uv tool install alchemux`
133
+ alchemux doctor
134
+ ```
135
+
136
+ | Problem | Solution |
137
+ |---------|----------|
138
+ | Config not found | Run `alchemux setup` or `alchemux doctor` — paths in [docs/install.md](docs/install.md) |
139
+ | Downloads fail | Try audio-only or `--flac`; run `alchemux update`; see [known-issues.md](docs/known-issues.md) (KI-002, KI-003) |
140
+ | `ffmpeg not found` | Install system FFmpeg (`brew install ffmpeg`, `apt install ffmpeg`, etc.) — [docs/install.md](docs/install.md) |
141
+
142
+ ## Contributing
143
+
144
+ Bug reports, feature requests, and feedback are welcome via **[GitHub Issues](https://github.com/bmurrtech/alchemux/issues/new/choose)**. Please read **[docs/known-issues.md](docs/known-issues.md)** first.
145
+
146
+ Maintainers: local tooling, tests, and CI — **[docs/contributors.md](docs/contributors.md)**. Release process — **[docs/release.md](docs/release.md)**.
147
+
148
+ ## Support open source
149
+
150
+ If Alchemux saves you time, consider:
151
+
152
+ - ⭐ **Starring the repo** — [![Star on GitHub](https://img.shields.io/badge/Star-on_GitHub-blue?logo=github)](https://github.com/bmurrtech/alchemux)
153
+ - 🐛 **[Open a GitHub Issue](https://github.com/bmurrtech/alchemux/issues/new/choose)** — bugs, ideas, and feedback
154
+ - 📣 **Sharing** with others who download or archive media from the terminal
155
+ - ☕ **[Buy Me a Coffee](https://www.buymeacoffee.com/bmurrtech)** or **[Ko-fi](https://ko-fi.com/bmurrtech)**
156
+
157
+ <p align="center">
158
+ <a href="https://www.buymeacoffee.com/bmurrtech" target="_blank" rel="noopener">
159
+ <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support%20the%20project-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black" alt="Buy Me a Coffee">
160
+ </a>
161
+ <a href="https://ko-fi.com/bmurrtech" target="_blank" rel="noopener">
162
+ <img src="https://img.shields.io/badge/Ko--fi-Support%20the%20project-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white" alt="Ko-fi">
163
+ </a>
164
+ </p>
165
+
166
+ ## Acknowledgements
167
+
168
+ - **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — core downloader
169
+ - **[FFmpeg](https://ffmpeg.org/)** — audio/video conversion (system install)
170
+ - **[uv](https://docs.astral.sh/uv/)** — install and run via `uv tool install` / `uvx`
171
+ - **[prek](https://github.com/j178/prek)** — pre-commit hooks in CI and locally
172
+ - **[PyPI](https://pypi.org/)** — package distribution
173
+ - **[Typer](https://typer.tiangolo.com/)**, **[Rich](https://github.com/Textualize/rich)**, **[InquirerPy](https://github.com/kazhala/InquirerPy)** — CLI UX
174
+ - **[pyperclip](https://github.com/pyperclip/pyperclip)**, **[mutagen](https://github.com/quodlibet/mutagen)**, **[python-dotenv](https://github.com/theskumar/python-dotenv)** — clipboard, metadata, env helpers
175
+
176
+ ## License
177
+
178
+ [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0.html)
179
+
180
+ This repository is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE). The badge links to the official license text; the [`LICENSE`](LICENSE) file in this repo is the binding copy.
181
+
182
+ ### License permissions and restrictions
183
+
184
+ *Keeping open-source open.*
185
+
186
+ | Use case | Permitted | Notes / conditions |
187
+ |----------|-----------|-------------------|
188
+ | Private / internal use | ✅ | No obligation to publish changes if you do not distribute or offer the software as a network service to others. |
189
+ | Modify for own private use | ✅ | Obligations attach when you distribute or run modified code as a networked service for users. |
190
+ | Share / distribute (unmodified) | ✅ | Include AGPL license and corresponding source (or compliant written offer). |
191
+ | Distribute with modifications | ✅ | Modified source must be available under AGPL-3.0 to recipients. |
192
+ | Provide as SaaS / network service | ✅ | Users interacting with your modified version over a network must be able to obtain complete corresponding source. |
193
+ | Closed / proprietary redistribution | ❌ | Public distribution or SaaS without corresponding source under AGPL is not allowed. |
194
+ | Restricting source access for users you serve | ❌ | Network users must be able to get complete corresponding source as AGPL defines. |
195
+ | Sublicensing under more restrictive terms | ❌ | AGPL terms must flow through. |
196
+
197
+ ### Commercial / proprietary licensing
198
+
199
+ Need use **without** AGPL copyleft (closed-source distribution, SaaS without source-offer obligations, etc.)? **Commercial licenses may be available.** Open a [GitHub Issue](https://github.com/bmurrtech/alchemux/issues/new/choose) to discuss licensing and pricing.
200
+
201
+ ---
202
+
203
+ ## Disclaimer
204
+
205
+ This software is provided **as-is**, without warranty of any kind. The author(s) are **not liable** for damages or losses from use of this project, including data loss, failed downloads, or cloud storage misconfiguration.
206
+
207
+ By using Alchemux you accept responsibility for:
208
+
209
+ - Complying with this license and the **terms of service** of sites you download from (e.g. YouTube)
210
+ - Ensuring **yt-dlp**, **FFmpeg**, and cloud provider usage comply with their respective licenses and policies
211
+ - Securing your own credentials for S3/GCP and local config files