Skip to content

MIGRATION_STATUS.md

Latest commit

 

History

History
308 lines (262 loc) · 10.8 KB

MIGRATION_STATUS.md

File metadata and controls

308 lines (262 loc) · 10.8 KB

Muine Migration Status - .NET 10 with Avalonia

Overview

This document tracks the progress of migrating Muine music player from Mono/GTK# to .NET 10 with Avalonia UI.

Status: Internet Radio Support Added ✅
Last Updated: December 16, 2025
Completion: ~60% (4 of 5 major phases complete)

Phase Status

✅ Phase 1: Project Structure (COMPLETE)

  • Modern .NET 10 solution structure
  • Three projects: Muine.App, Muine.Core, Muine.Tests
  • Avalonia 11.3.9 UI framework
  • Proper separation of concerns
  • Build system working perfectly

✅ Phase 2: Core Business Logic (COMPLETE)

All core services and models implemented with comprehensive tests:

Models:

  • Song.cs: Modern POCO for song metadata
  • Album.cs: Album grouping model

Services:

  • MetadataService.cs: Reads audio file metadata using TagLib-Sharp
  • MusicDatabaseService.cs: SQLite database CRUD operations
  • LibraryScannerService.cs: Directory scanning and music import

Tests: 95 tests, all passing

  • Song model: 8 tests
  • Album model: 6 tests
  • Database service: 3 tests
  • Metadata service: 9 tests
  • Cover art service: 5 tests
  • Library scanner: 8 tests
  • Playback service: 7 tests
  • Radio station model: 7 tests
  • Radio category model: 4 tests
  • Radio station service: 11 tests
  • Playlist: 27 tests
  • Music library: 10 tests

✅ Phase 3: Audio Backend (COMPLETE)

Status: LibVLCSharp integration complete

Completed:

  • ✅ LibVLCSharp cross-platform audio library integration
  • ✅ PlaybackService with play/pause/stop/seek functionality
  • ✅ Volume control
  • ✅ Position/duration tracking for progress display
  • ✅ PlaybackState management (Playing, Paused, Stopped)
  • ✅ ReplayGain support from metadata
  • ✅ Event-driven architecture for state changes
  • ✅ Comprehensive unit tests (7 tests)
  • ✅ Graceful handling when LibVLC is not available

Technical Details:

  • Uses LibVLCSharp 3.9.0 with native libraries for Windows/Mac/Linux
  • Timer-based position updates (100ms interval)
  • Automatic ReplayGain application from song metadata
  • Disposed properly to release resources

🟢 Phase 4: UI Implementation (SUBSTANTIALLY COMPLETE)

Status: Core features complete, advanced features pending

Completed:

  • ✅ Main window XAML layout
  • ✅ Player controls UI with functional bindings
  • ✅ Play/Pause/Stop buttons with commands
  • ✅ Progress slider with position tracking
  • ✅ Time display (current/total duration)
  • ✅ Volume slider
  • ✅ Song selection and double-click to play
  • ✅ Current song display
  • ✅ Menu structure
  • ✅ Music import functionality (folder and files)
  • ✅ Song list display
  • ✅ Internet Radio Support
    • ✅ Radio tab with station list and category tree
    • ✅ Add/Edit radio station dialog
    • ✅ Stream URL metadata extraction (PLS, M3U, ICY)
    • ✅ Hierarchical categorization (Parent > Sub categories)
    • ✅ Radio station playback through LibVLC
    • ✅ Database storage for stations and categories
    • ✅ Search functionality for local stations
    • ✅ Last played tracking
    • ✅ Online Station Search (NEW)
      • ✅ Search Radio-Browser.info API for stations worldwide
      • ✅ Unified search by name, city, and genre in single search box
      • ✅ Add discovered stations to local library
      • ✅ Two-tab interface: My Stations & Search Online

Needed:

  • Additional dialogs (About)
  • Cover art display in player
  • Playlist visualization improvements
  • Album sidebar implementation
  • Previous/Next track functionality

🔴 Phase 5: Configuration & Platform Integration (NOT STARTED)

Priority: MEDIUM

Needed:

  • Configuration service (replace GConf)
  • Settings storage (JSON/XML)
  • Platform integration (media keys, notifications)
  • Plugin system modernization

Quick Start for Developers

Build & Test

cd /home/runner/work/Muine/Muine
dotnet build
dotnet test

Run Application

cd src/Muine.App
dotnet run

Project Structure

Muine/
├── src/
│   ├── Muine.App/              # Avalonia UI
│   │   ├── Views/              # XAML views (MainWindow, RadioView, etc.)
│   │   └── ViewModels/         # View models (MainWindowViewModel, RadioViewModel, etc.)
│   └── Muine.Core/             # Business logic
│       ├── Models/             # Data models
│       │   ├── Song.cs
│       │   ├── Album.cs
│       │   ├── RadioStation.cs
│       │   └── RadioCategory.cs
│       └── Services/           # Services
│           ├── MetadataService.cs
│           ├── MusicDatabaseService.cs
│           ├── LibraryScannerService.cs
│           ├── RadioStationService.cs
│           └── RadioMetadataService.cs
└── tests/                      # Unit & integration tests
    ├── Models/
    └── Services/

Next Steps (Priority Order)

  1. Manual Testing & Bug Fixes

    • Test radio streaming with various formats (MP3, OGG, AAC streams)
    • Test PLS and M3U playlist parsing
    • Verify ICY metadata extraction
    • Test hierarchical category display

  2. Playlist Management (Phase 4)

    • Implement playlist queue
    • Add/remove songs functionality
    • Previous/Next track navigation
    • Save/load playlists

  3. Album View (Phase 4)

    • Populate album sidebar
    • Group songs by album
    • Album selection and playback

  4. Cover Art Display (Phase 4)

    • Display cover art in player
    • Implement cover art downloading (MusicBrainz/Amazon)
    • Album art grid view

  5. Configuration System (Phase 5)

    • Create settings service
    • Implement preferences dialog
    • Store user settings (volume, last played, etc.)

  6. Platform Integration (Phase 5)

    • Media keys support
    • System notifications
    • System tray integration

Technical Decisions Made

Why SQLite?

  • Cross-platform
  • No external server needed
  • Better performance than GDBM
  • Wide .NET support
  • ACID compliance

Why Avalonia?

  • True cross-platform (Linux, Windows, macOS)
  • XAML-based (familiar to WPF/UWP developers)
  • Active development and community
  • Good performance
  • Modern UI capabilities

Why TagLib-Sharp?

  • Already used in original Muine
  • Cross-platform
  • Supports multiple formats
  • Well-maintained
  • Familiar API

Known Issues

None currently. All tests passing (note: some MusicBrainz API tests may fail intermittently due to rate limiting).

New Features (Beyond Original Muine)

Enhanced Metadata and MP3 Tagging (NEW)

Muine now includes comprehensive MusicBrainz integration for automatic metadata enhancement:

  • MusicBrainz API Integration: Search and match songs to MusicBrainz database
  • Automatic Matching: Match local files and YouTube songs to MusicBrainz entries
  • ID3 Tag Writing: Write enhanced metadata to MP3, FLAC, OGG files including:
    • Artist, Title, Album, Year, Track Number
    • MusicBrainz Recording/Release/Artist IDs
    • Genres/Tags from MusicBrainz
  • Album Artwork: Download and embed cover art from Cover Art Archive
  • Disambiguation Support: Handle multiple matches with confidence scoring
  • Background Queue: Process metadata enhancement in background with rate limiting
  • Rate Limit Compliance: Respects MusicBrainz 1 request/second limit
  • YouTube Enhancement: Automatically enhance YouTube song metadata

Services:

  • MusicBrainzService: Query MusicBrainz API with rate limiting
  • MetadataEnhancementService: Orchestrate matching and enhancement
  • BackgroundTaggingQueue: Background processing queue for metadata updates
  • Extended MetadataService: Write tags and embed artwork

Usage:

// Enhance a single song
var enhancementService = new MetadataEnhancementService();
var (enhancedSong, match) = await enhancementService.EnhanceSongAsync(song);

// Queue multiple songs for background processing
var taggingQueue = new BackgroundTaggingQueue();
taggingQueue.EnqueueSongs(songs);

// Auto-enhance during library scan
var scanner = new LibraryScannerService(metadata, database, coverArt, taggingQueue);
await scanner.ScanDirectoryAsync(path, progress, autoEnhanceMetadata: true);

Internet Radio Support

Muine now includes comprehensive internet radio station support:

  • Stream Support: Play HTTP audio streams (MP3, OGG, AAC, etc.)
  • Playlist Parsing: Automatically parse PLS and M3U playlist files
  • Metadata Extraction: Extract station info from ICY headers
  • Hierarchical Categories: Organize stations by genre/location (e.g., "Music > Rock", "Sports > Atlanta")
  • Station Management: Add, edit, delete stations via UI
  • Search: Search stations by name, genre, or location
  • Persistence: Stations stored in SQLite database
  • Last Played Tracking: Remember when each station was last played

Usage Example:

  1. Click "Radio" tab
  2. Click "Add Station"
  3. Enter stream URL (e.g., http://example.com/stream.m3u)
  4. Click "Extract Metadata" to auto-fill station details
  5. Optionally categorize with Parent Category (e.g., "Music") and Sub Category (e.g., "Rock")
  6. Double-click station to play

Dependencies

<!-- Core Library -->
<PackageReference Include="TagLibSharp" Version="2.3.0" />
<PackageReference Include="Microsoft.Data.Sqlite" Version="10.0.1" />
<PackageReference Include="LibVLCSharp" Version="3.9.0" />
<PackageReference Include="RadioBrowser" Version="0.7.0" />
<PackageReference Include="MetaBrainz.MusicBrainz" Version="7.0.0" />
<PackageReference Include="VideoLAN.LibVLC.Windows" Version="3.0.21" />
<PackageReference Include="VideoLAN.LibVLC.Mac" Version="3.0.21" />

<!-- Application -->
<PackageReference Include="Avalonia" Version="11.3.9" />
<PackageReference Include="Avalonia.Desktop" Version="11.3.9" />
<PackageReference Include="Avalonia.Themes.Fluent" Version="11.3.9" />
<PackageReference Include="Avalonia.Controls.DataGrid" Version="11.3.9" />
<PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.1" />

<!-- Testing -->
<PackageReference Include="xunit" Version="2.9.3" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />

Performance Notes

  • Database operations are async to avoid UI blocking
  • File scanning uses async I/O
  • Large music libraries should be scanned in background
  • MusicBrainz queries are rate-limited (1 req/sec) and processed in background queue
  • Consider implementing caching for album artwork

Testing Strategy

  • Unit tests for all models and services
  • Integration tests for database operations
  • MusicBrainz API tests (may require internet connection)
  • UI tests (pending Avalonia UI completion)
  • Manual testing on Linux (primary target platform)

Resources