# dmx - Interactive Music Search & Download
Interactive music search and download tool with Deezer integration. Browse artists, view their profiles, and download albums directly from the command line.
## ✨ Features
### 🎵 **Advanced Artist Browsing**
- **Artist Search & Profiles**: Search artists and view detailed profiles with top songs
- **Complete Album Collections**: Browse ALL albums from any artist (sorted by popularity)
- **Direct Album Downloads**: Download any album by simply typing its number
- **Smart Sorting**: Artists sorted by fan count for better discovery
### 🎯 **Interactive Experience**
- **Multi-Mode Search**: Switch between tracks, albums, and artists instantly
- **Intuitive Navigation**: Browse artist profiles with `back` command support
- **Visual Feedback**: Color-coded interface with progress indicators
- **Smart Detection**: Avoids re-downloading existing files
### ⚡ **Quality & Performance**
- **Quality Downloads**: Automatic quality fallback (320kbps → 128kbps → available)
- **Batch Operations**: Efficient album downloads with progress tracking
- **ARL Authentication**: Secure authentication using Deezer ARL tokens
- **Cross-Platform**: Works on Windows, macOS, and Linux
## 📦 Installation
### Using pip (Recommended)
```bash
pip install dmx-music
```
### Using Nix
```bash
# Install directly from GitHub
nix run github:cargaona/dmx
# Or add to your flake inputs
{
inputs.dmx.url = "github:cargaona/dmx";
}
```
### From source
```bash
git clone https://github.com/cargaona/dmx.git
cd dmx
pip install -e .
```
## Quick Start
1. **Get your ARL token** from Deezer (check browser cookies)
2. **Configure dmx**:
```bash
dmx config set arl YOUR_ARL_TOKEN_HERE
dmx config set quality 320
dmx config set output ~/Music
```
3. **Start interactive mode**:
```bash
dmx
```
4. **Search and download**:
```
[tracks] > lady gaga disease
[tracks] > 1 # Download first result
```
## 🎨 Artist Browsing Workflow
**Featured in v0.1.0**: Complete artist profile browsing with album downloads
```bash
# Switch to artists mode
[tracks] > m artists
# Search for artists (sorted by fan count)
[artists] > pez
# View artist profile
[artists] > 2 # Select Pez with 10,580 fans
# Browse ALL artist albums (72 total)
[Pez Albums] > l # List all albums
# Download any album directly
[Pez Albums] > 15 # Download album #15
# Navigate back
[Pez Albums] > back
[artists] >
```
### Example Artist Profile:
```
🎤 Artist Profile
Pez
72 albums • 10,580 fans
🎵 Top Songs:
Aire al Fin
El Manto Eléctrico • 3:13
💿 Albums (Enter number to download):
1 Goodbye Dear, Ok Chicago. (11 tracks)
2 Ion (13 tracks)
[... 70 more albums ...]
Commands: [number] = download album | 'back' = return to artist search
```
## Usage
### Interactive Mode (Default)
```bash
dmx
```
Commands available in interactive mode:
- `<query>` - Search for tracks
- `sa <query>` - Search albums
- `st <query>` - Search artists
- `<number>` - Download by number
- `m tracks|albums|artists` - Switch mode
- `l` - List current results
- `status` - Show system status
- `q` - Quit
### Direct Commands
```bash
# Search
dmx search "artist song"
dmx search -a "album name"
dmx search -t "artist name"
# Download by URL
dmx download "https://www.deezer.com/track/123456"
dmx download "https://www.deezer.com/album/123456"
# Configuration
dmx config list
dmx config set quality 320
dmx config set output ~/Music
# System status
dmx status
```
## Configuration
Configuration is stored in `~/.config/dmx/config.json`.
### Available Settings
- `arl` - Your Deezer ARL token (required for downloads)
- `quality` - Audio quality: `128`, `320`, or `FLAC`
- `output` - Download directory (default: `~/Downloads/Music`)
### Getting ARL Token
1. Open Deezer in your browser
2. Log in to your account
3. Open Developer Tools (F12)
4. Go to Application/Storage → Cookies
5. Find the `arl` cookie value
6. Copy the value and use it with `dmx config set arl YOUR_TOKEN`
**Note**: You need a Deezer Premium subscription for high-quality downloads.
## Examples
### Search and Download
```bash
# Interactive search
dmx
# Search for a specific song
[tracks] > bruno mars finesse
1 Finesse (Remix; feat. Cardi B)
by Bruno Mars • Finesse (feat. Cardi B) (Remix) • 3:37
# Download it
[tracks] > 1
✓ Downloaded: Bruno Mars - Finesse (Remix; feat. Cardi B).mp3
```
### Album Downloads
```bash
# Switch to album mode
[tracks] > m albums
# Search for album
[albums] > lady gaga mayhem
1 MAYHEM
by Lady Gaga • 14 tracks
# Download entire album
[albums] > 1
✓ Downloaded 14 files
```
### Direct URL Downloads
```bash
# Download specific track
dmx download "https://www.deezer.com/track/123456"
# Download entire album
dmx download "https://www.deezer.com/album/123456"
```
## File Organization
Downloaded files are organized as:
```
~/Downloads/Music/
├── Artist - Album/
│ ├── 01 - Track Name.mp3
│ ├── 02 - Another Track.mp3
│ └── ...
└── Artist - Single Track.mp3
```
## Requirements
- Python 3.8+
- Valid Deezer ARL token
- Internet connection
## Development
### Using Nix
```bash
# Enter development shell
nix develop
# Install in development mode
python -m pip install -e .
# Run tests
pytest
```
### Manual Setup
```bash
# Clone repository
git clone https://github.com/cargaona/dmx.git
cd dmx
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
# or
venv\\Scripts\\activate # Windows
# Install dependencies
pip install -e .
# Run tests
pytest
```
## License
MIT License - see [LICENSE](LICENSE) for details.
## Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.
## Acknowledgments
- Built on [deemix](https://deemix.app) - the core download engine
- Uses [Deezer](https://deezer.com) for music metadata and streaming
Raw data
{
"_id": null,
"home_page": null,
"name": "dmx-music",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "music, download, deezer, deemix, audio, interactive, cli, artist, album, search",
"author": null,
"author_email": "cargaona <cargaona@users.noreply.github.com>",
"download_url": null,
"platform": null,
"description": "# dmx - Interactive Music Search & Download\n\nInteractive music search and download tool with Deezer integration. Browse artists, view their profiles, and download albums directly from the command line.\n\n## \u2728 Features\n\n### \ud83c\udfb5 **Advanced Artist Browsing**\n- **Artist Search & Profiles**: Search artists and view detailed profiles with top songs\n- **Complete Album Collections**: Browse ALL albums from any artist (sorted by popularity) \n- **Direct Album Downloads**: Download any album by simply typing its number\n- **Smart Sorting**: Artists sorted by fan count for better discovery\n\n### \ud83c\udfaf **Interactive Experience**\n- **Multi-Mode Search**: Switch between tracks, albums, and artists instantly\n- **Intuitive Navigation**: Browse artist profiles with `back` command support\n- **Visual Feedback**: Color-coded interface with progress indicators\n- **Smart Detection**: Avoids re-downloading existing files\n\n### \u26a1 **Quality & Performance**\n- **Quality Downloads**: Automatic quality fallback (320kbps \u2192 128kbps \u2192 available)\n- **Batch Operations**: Efficient album downloads with progress tracking\n- **ARL Authentication**: Secure authentication using Deezer ARL tokens\n- **Cross-Platform**: Works on Windows, macOS, and Linux\n\n## \ud83d\udce6 Installation\n\n### Using pip (Recommended)\n\n```bash\npip install dmx-music\n```\n\n### Using Nix\n\n```bash\n# Install directly from GitHub\nnix run github:cargaona/dmx\n\n# Or add to your flake inputs\n{\n inputs.dmx.url = \"github:cargaona/dmx\";\n}\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cargaona/dmx.git\ncd dmx\npip install -e .\n```\n\n## Quick Start\n\n1. **Get your ARL token** from Deezer (check browser cookies)\n\n2. **Configure dmx**:\n ```bash\n dmx config set arl YOUR_ARL_TOKEN_HERE\n dmx config set quality 320\n dmx config set output ~/Music\n ```\n\n3. **Start interactive mode**:\n ```bash\n dmx\n ```\n\n4. **Search and download**:\n ```\n [tracks] > lady gaga disease\n [tracks] > 1 # Download first result\n ```\n\n## \ud83c\udfa8 Artist Browsing Workflow\n\n**Featured in v0.1.0**: Complete artist profile browsing with album downloads\n\n```bash\n# Switch to artists mode\n[tracks] > m artists\n\n# Search for artists (sorted by fan count)\n[artists] > pez\n\n# View artist profile\n[artists] > 2 # Select Pez with 10,580 fans\n\n# Browse ALL artist albums (72 total)\n[Pez Albums] > l # List all albums\n\n# Download any album directly \n[Pez Albums] > 15 # Download album #15\n\n# Navigate back\n[Pez Albums] > back\n[artists] > \n```\n\n### Example Artist Profile:\n```\n\ud83c\udfa4 Artist Profile\nPez\n 72 albums \u2022 10,580 fans\n\n\ud83c\udfb5 Top Songs:\n Aire al Fin\n El Manto El\u00e9ctrico \u2022 3:13\n\n\ud83d\udcbf Albums (Enter number to download):\n 1 Goodbye Dear, Ok Chicago. (11 tracks)\n 2 Ion (13 tracks)\n [... 70 more albums ...]\n\nCommands: [number] = download album | 'back' = return to artist search\n```\n\n## Usage\n\n### Interactive Mode (Default)\n\n```bash\ndmx\n```\n\nCommands available in interactive mode:\n- `<query>` - Search for tracks\n- `sa <query>` - Search albums \n- `st <query>` - Search artists\n- `<number>` - Download by number\n- `m tracks|albums|artists` - Switch mode\n- `l` - List current results\n- `status` - Show system status\n- `q` - Quit\n\n### Direct Commands\n\n```bash\n# Search\ndmx search \"artist song\"\ndmx search -a \"album name\"\ndmx search -t \"artist name\"\n\n# Download by URL\ndmx download \"https://www.deezer.com/track/123456\"\ndmx download \"https://www.deezer.com/album/123456\"\n\n# Configuration\ndmx config list\ndmx config set quality 320\ndmx config set output ~/Music\n\n# System status\ndmx status\n```\n\n## Configuration\n\nConfiguration is stored in `~/.config/dmx/config.json`.\n\n### Available Settings\n\n- `arl` - Your Deezer ARL token (required for downloads)\n- `quality` - Audio quality: `128`, `320`, or `FLAC`\n- `output` - Download directory (default: `~/Downloads/Music`)\n\n### Getting ARL Token\n\n1. Open Deezer in your browser\n2. Log in to your account\n3. Open Developer Tools (F12)\n4. Go to Application/Storage \u2192 Cookies\n5. Find the `arl` cookie value\n6. Copy the value and use it with `dmx config set arl YOUR_TOKEN`\n\n**Note**: You need a Deezer Premium subscription for high-quality downloads.\n\n## Examples\n\n### Search and Download\n```bash\n# Interactive search\ndmx\n\n# Search for a specific song\n[tracks] > bruno mars finesse\n1 Finesse (Remix; feat. Cardi B)\n by Bruno Mars \u2022 Finesse (feat. Cardi B) (Remix) \u2022 3:37\n\n# Download it\n[tracks] > 1\n\u2713 Downloaded: Bruno Mars - Finesse (Remix; feat. Cardi B).mp3\n```\n\n### Album Downloads\n```bash\n# Switch to album mode\n[tracks] > m albums\n\n# Search for album\n[albums] > lady gaga mayhem\n1 MAYHEM\n by Lady Gaga \u2022 14 tracks\n\n# Download entire album\n[albums] > 1\n\u2713 Downloaded 14 files\n```\n\n### Direct URL Downloads\n```bash\n# Download specific track\ndmx download \"https://www.deezer.com/track/123456\"\n\n# Download entire album\ndmx download \"https://www.deezer.com/album/123456\"\n```\n\n## File Organization\n\nDownloaded files are organized as:\n```\n~/Downloads/Music/\n\u251c\u2500\u2500 Artist - Album/\n\u2502 \u251c\u2500\u2500 01 - Track Name.mp3\n\u2502 \u251c\u2500\u2500 02 - Another Track.mp3\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 Artist - Single Track.mp3\n```\n\n## Requirements\n\n- Python 3.8+\n- Valid Deezer ARL token\n- Internet connection\n\n## Development\n\n### Using Nix\n\n```bash\n# Enter development shell\nnix develop\n\n# Install in development mode\npython -m pip install -e .\n\n# Run tests\npytest\n```\n\n### Manual Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/cargaona/dmx.git\ncd dmx\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # Linux/macOS\n# or\nvenv\\\\Scripts\\\\activate # Windows\n\n# Install dependencies\npip install -e .\n\n# Run tests\npytest\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## Acknowledgments\n\n- Built on [deemix](https://deemix.app) - the core download engine\n- Uses [Deezer](https://deezer.com) for music metadata and streaming\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Interactive music search and download tool with Deezer integration - browse artists, albums, and download music",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/cargaona/dmx/issues",
"Homepage": "https://github.com/cargaona/dmx",
"Source": "https://github.com/cargaona/dmx"
},
"split_keywords": [
"music",
" download",
" deezer",
" deemix",
" audio",
" interactive",
" cli",
" artist",
" album",
" search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "30879341cae19a13e6bebac82d439fdc17a1c533d800c2a0db22985fe12a2ef8",
"md5": "d9ad1b1de8bc0191d75532cece280ac2",
"sha256": "941aa15910acc59f08c45ad4eede736c1616ceaf3adbdcdfdd1af8793b6f1ddf"
},
"downloads": -1,
"filename": "dmx_music-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9ad1b1de8bc0191d75532cece280ac2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41324,
"upload_time": "2025-07-21T23:58:10",
"upload_time_iso_8601": "2025-07-21T23:58:10.150076Z",
"url": "https://files.pythonhosted.org/packages/30/87/9341cae19a13e6bebac82d439fdc17a1c533d800c2a0db22985fe12a2ef8/dmx_music-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 23:58:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cargaona",
"github_project": "dmx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dmx-music"
}
JSON
