qobuz-import

A CLI tool to import tracklists from music websites into Qobuz playlists.

Status

Alpha - Core functionality works but limited to 1001tracklists.com as a source.

Supported Sources

• 1001tracklists.com

Features

• Parse tracklists from supported URLs
• Fuzzy matching against Qobuz catalog (with ISRC exact match when available)
• Interactive mode for manual track selection when fuzzy matching fails
• Dry-run mode to preview parsed tracks without creating a playlist
• Headless browser with stealth mode (optional visible mode for captcha solving)

Requirements

• Node.js >= 18.0.0
• A Qobuz account

Installation

git clone https://github.com/jfmoy/qobuz-import.git
cd qobuz-import
npm install
npm run build

Configuration

Copy .env.example to .env and configure your Qobuz credentials:

cp .env.example .env

QOBUZ_EMAIL=your@email.com
QOBUZ_PASSWORD=yourpassword

Credentials can also be provided via CLI flags or entered interactively when prompted.

Usage

# Basic usage
npm start -- <tracklist-url>

# With options
npm start -- <tracklist-url> --name "My Playlist" --interactive

# Dry-run (preview without creating playlist)
npm start -- <tracklist-url> --dry-run

# Show browser window (for manual captcha solving)
npm start -- <tracklist-url> --visible

CLI Options

Option	Description
-e, --email <email>	Qobuz account email
-n, --name <name>	Custom playlist name
-d, --dry-run	Show parsed tracks without creating playlist
-i, --interactive	Manually select matches for unmatched tracks
--visible	Show browser window (useful for captcha)
--debug	Output debug information

Example

npm start -- "https://www.1001tracklists.com/tracklist/example" --name "Festival Set 2024" --interactive

Development

# Run in development mode
npm start -- <url>

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Format
npm run format

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Follow Conventional Commits for commit messages
4. Ensure tests pass (npm test) and code is linted (npm run lint)
5. Submit a Pull Request

Adding New Sources

The project uses a registry pattern for source extractors. To add support for a new website:

1. Create an extractor service in src/sources/extractors/
2. Implement the SourceExtractor interface
3. Register it in the SourceParserService

License

MIT - Jean-Francois Moy