mdlx-cli 0.0.1

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 (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +122 -0
  3. package/dist/cli.js +526 -0
  4. package/package.json +71 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 mdl contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,122 @@
1
+ # mdl MusicDownLoader
2
+
3
+ > WARNING: under active development!!
4
+
5
+ `mdl` is MusicDownLoader, a terminal music downloader for people who want to sync music locally.
6
+
7
+ Paste a URL, and the tool resolves music metadata, searches YouTube for matches, and downloads tracks. It stores a local sync manifest so future runs can reconcile the folder instead of starting over.
8
+
9
+ ## Provider support
10
+
11
+ Recognized providers:
12
+
13
+ - Spotify
14
+ - Apple Music
15
+ - Amazon Music
16
+ - YouTube Music
17
+ - SoundCloud
18
+ - Bandcamp
19
+ - Qobuz
20
+ - Deezer
21
+ - Tidal
22
+
23
+ Current implementation status:
24
+
25
+ - Music metadata import is attempted for every provider listed above.
26
+ - Spotify still has the most direct/robust metadata path in the current implementation.
27
+ - Audio downloads currently come from YouTube matches for all supported flows.
28
+
29
+ ## Why use it
30
+
31
+ - Interactive CLI
32
+ - Links work without API keys, we query via public urls
33
+ - Downloads are grouped into a music name directory
34
+ - A `_mdl.json` manifest is written next to the files for resyncs
35
+ - Metadata is resolved directly from the music URL
36
+ - Audio is currently sourced from YouTube
37
+
38
+ ## Install
39
+
40
+ `ffmpeg` must already be installed and available on your `PATH`.
41
+
42
+ ### Homebrew (COMING SOON)
43
+
44
+ ```bash
45
+ brew tap labithiotis/mdl
46
+ brew install mdl
47
+ ```
48
+
49
+ ### Manual
50
+
51
+ Download the archive for your platform from the project's Releases page, extract the binary, and move it somewhere on your `PATH`.
52
+
53
+ ```bash
54
+ chmod +x mdl
55
+ mv mdl /usr/local/bin/mdl
56
+ mdl --help
57
+ ```
58
+
59
+ ## Usage
60
+
61
+ Run the interactive CLI:
62
+
63
+ ```bash
64
+ mdl
65
+ ```
66
+
67
+ Pass a playlist URL directly:
68
+
69
+ ```bash
70
+ mdl "https://open.spotify.com/playlist/..."
71
+ ```
72
+
73
+ Choose a base output directory:
74
+
75
+ ```bash
76
+ mdl "https://open.spotify.com/playlist/..." --output ./music
77
+ ```
78
+
79
+ Control how many tracks download in parallel:
80
+
81
+ ```bash
82
+ mdl "https://open.spotify.com/playlist/..." --parallel 5
83
+ ```
84
+
85
+ Choose the extracted audio format and quality:
86
+
87
+ ```bash
88
+ mdl "https://open.spotify.com/playlist/..." --format m4a --bitrate 192K
89
+ ```
90
+
91
+ CLI help:
92
+
93
+ ```bash
94
+ mdl --help
95
+ ```
96
+
97
+ `pnpm test` runs the end-to-end CLI test, which performs a real download and can take several minutes.
98
+
99
+ ## Contributing
100
+
101
+ Issues and pull requests are welcome. Before opening a PR:
102
+
103
+ 1. Run `pnpm lint`, `pnpm check`, and `pnpm test`.
104
+ 2. Update the documentation if CLI behavior changes.
105
+ 3. Keep changes focused and explain any test gaps.
106
+
107
+ See `CONTRIBUTING.md` for the contribution workflow, `CODE_OF_CONDUCT.md` for community expectations, and `SECURITY.md` for responsible disclosure.
108
+
109
+ ## Example urls
110
+
111
+ ```txt
112
+ https://open.spotify.com/playlist/37i9dQZF1E37peeAkY9IZs?si=mVwl4zfbTQujVX8-PleBkw
113
+ https://open.spotify.com/album/6eUW0wxWtzkFdaEFsTJto6
114
+ https://music.apple.com/us/playlist/new-music-daily/pl.2b0e6e332fdf4b7a91164da3162127b5
115
+ https://music.amazon.com/playlists/B01M11SBC8
116
+ https://soundcloud.com/soundcloud-amped/sets/the-dive-new-rock-now
117
+ https://bandcamp.com/sergemedoff/playlist/leipzig-de-rockpop-mix
118
+ https://link.deezer.com/s/32LXyVEY8jkF9wlGiSwa1
119
+ https://www.qobuz.com/us-en/playlists/hi-res-masters-jazz-essentials/5104639
120
+ https://tidal.com/playlist/36ea71a8-445e-41a4-82ab-6628c581535d
121
+ https://music.youtube.com/playlist?list=RDCLAK5uy_nHSqCJjDrW9HBhCNdF6tWPdnOMngOv0wA&playnext=1&si=D5Aj97tJAaxyFE4c
122
+ ```