IBroadcastStars

A .NET 8 console application to synchronize "liked" tracks from your Apple Music library to iBroadcast.

Français

Features

• 🎵 Unidirectional sync: Apple Music → iBroadcast
• ❤️ Smart "liked" detection: A track is considered "liked" if it has a "Liked" status OR at least 1 star rating
• 🎯 Intelligent matching: Levenshtein distance algorithm with quality scores (title 60% + artist 40%)
• 🔐 OAuth2 authentication: Secure Device Code Flow with automatic token refresh
• 📊 Preview mode: See all changes before synchronization (--preview-only)
• 🔄 Interactive mode: Confirm uncertain matches (score < 80%)
• ⚡ Optimized matching: Artist indexing and caching for fast processing
• 💾 Auto-detection: Automatically finds your iTunes XML or Apple Music library
• ⚠️ Rate limiting: Built-in delays to respect iBroadcast API limits

Apple Music library parsing is powered by AppMusicLibParser.

How It Works

Sync Logic

Unidirectional synchronization: Apple Music → iBroadcast

A track is considered "liked" on Apple Music if:

• LikeStatus == Liked OR
• Rating >= 1 star (≥ 20 on the 0-100 scale)

If liked → ThumbsUp on iBroadcast
Otherwise → NoThumb on iBroadcast

Matching Algorithm

The matcher uses:

• Levenshtein distance for string similarity
• Score: Title (60%) + Artist (40%)
• Quality levels:
  • Perfect: 100%
  • Excellent: 90-99%
  • Good: 80-89%
  • Uncertain: < 80% (requires confirmation in interactive mode)

Performance Optimizations

• Artist-based indexing to reduce search space
• String normalization caching
• Early exit on perfect matches
• 500ms delay between API calls to respect rate limits

Prerequisites

• .NET 8 SDK
• An iBroadcast account
• iTunes library (XML) or macOS Apple Music app

Setup

1. Create an iBroadcast Application

1. Go to media.ibroadcast.com
2. Open sidebar > Apps > developer
3. Create a new application
4. Note your client_id and client_secret
5. If using Apple Music library: obtain the AES decryption key for MusicDB files (not provided here for legal reasons, but findable with some research...)

2. Build the Application

dotnet build

3. Configure Credentials (Recommended: .env file)

Copy the example file and fill in your credentials:

cp .env.example .env

Edit .env and add your credentials:

IBROADCAST_CLIENT_ID=your_client_id_here
IBROADCAST_CLIENT_SECRET=your_client_secret_here

# Optional if using Apple Music app
MUSICDB_AES_KEY=the_aes_key_here

# Optional: custom library path
# LIBRARY_PATH=/path/to/iTunes Library.xml

Usage

Available Commands

# Sync command (default)
dotnet run --project IBroadcastStars.App sync [options]

# Info command - Display library information
dotnet run --project IBroadcastStars.App info [options]

# Stats command - Show detailed statistics
dotnet run --project IBroadcastStars.App stats [options]

Method 1: With .env File (Recommended)

Once .env is configured, simply run:

dotnet run --project IBroadcastStars.App sync

Method 2: Environment Variables

export IBROADCAST_CLIENT_ID=your_id
export IBROADCAST_CLIENT_SECRET=your_secret
export MUSICDB_AES_KEY=the_aes_key_here
dotnet run --project IBroadcastStars.App sync

Method 3: Command-Line Arguments

dotnet run --project IBroadcastStars.App sync -- \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

First Sync (OAuth Authentication)

On first run, the app will:

1. Display a code and URL
2. Ask you to open the URL in your browser
3. Enter the displayed code
4. Token will be saved in ~/.ibroadcast_token.json

Subsequent Syncs

Once authenticated, tokens are automatically refreshed when running the app.

Sync Options

--client-id <id>           iBroadcast app Client ID
--client-secret <secret>   iBroadcast app Client Secret
--library <path>           Path to your music library
                          (auto-detection if not specified)
--interactive, -i          Interactive mode to confirm uncertain matches
--reset-unrated, -r        Reset unrated tracks on iBroadcast to NoThumb
--preview-only, -p         Preview mode only (no synchronization)

Examples

Preview changes without syncing:

dotnet run --project IBroadcastStars.App sync --preview-only

With .env file (simplest):

# Configure .env once, then:
dotnet run --project IBroadcastStars.App sync

Interactive mode:

dotnet run --project IBroadcastStars.App sync --interactive

Reset unrated tracks:

dotnet run --project IBroadcastStars.App sync --reset-unrated

Custom library path (overrides .env):

dotnet run --project IBroadcastStars.App sync --library ~/Music/iTunes/iTunes\ Library.xml

Without .env file (direct arguments):

dotnet run --project IBroadcastStars.App sync -- \
  --client-id abc123 \
  --client-secret xyz789 \
  --reset-unrated

Project Structure

IBroadcastStars/
├── IBroadcastStars.App/
│   ├── Program.cs                         # Entry point and CLI setup
│   ├── Commands/
│   │   ├── SyncCommand.cs                 # Sync command implementation
│   │   ├── InfoCommand.cs                 # Info command
│   │   └── StatsCommand.cs                # Stats command
│   ├── IBroadcastApi/
│   │   ├── IBroadcastApiClient.cs         # HTTP client for iBroadcast API
│   │   ├── IIBroadcastApiClient.cs        # Client interface
│   │   ├── ApiModels.cs                   # API data models
│   │   └── OAuth/
│   │       ├── OAuth2Service.cs           # OAuth2 Device Code Flow
│   │       └── TokenResponse.cs           # OAuth response models
│   ├── Sync/
│   │   ├── SyncServices.cs                # Synchronization service
│   │   ├── TrackMatcher.cs                # Intelligent matching algorithm
│   │   └── SyncPreview.cs                 # Preview and statistics
│   ├── LocalLibraryParsers/
│   │   ├── ITunesLibraryParser.cs         # iTunes XML parser
│   │   ├── AppleMusicLibraryParser.cs     # Apple Music SQLite parser
│   │   ├── IMusicLibraryParser.cs         # Parser interface
│   │   ├── MusicLibraryParserFactory.cs   # Factory with auto-detection
│   │   └── Models/                        # Library data models
│   ├── Infrastructure/
│   │   ├── TypeRegistrar.cs               # DI registrar for Spectre.Console
│   │   └── TypeResolver.cs                # DI resolver
│   └── Extensions/
│       └── IBroadcastOptions.cs           # Configuration options
└── IBroadcastStars.Tests/
    └── (Unit tests)

Development

Tests

dotnet test

VS Code

Press F5 to debug, or use tasks:

• Build - Compile the solution
• Test - Run tests
• Run - Execute the application

Security

• OAuth2 tokens are stored in ~/.ibroadcast_token.json with 600 permissions (user read/write only)
• Client secrets can be passed via command line (consider using environment variables for better security)
• Tokens are automatically refreshed when they expire

Performance

For a library with ~700 liked tracks:

• Matching: < 1 second (with optimizations)
• Synchronization: ~6 minutes (500ms delay between API calls to respect rate limits)

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Copyright (C) 2026 IBroadcastStars Contributors

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

Credits

• Apple Music library parsing powered by AppMusicLibParser
• CLI framework: Spectre.Console