MusicCurator for YouTube Music MusicCurator is a Windows desktop app for exploring and managing your YouTube Music data. It is built with WinUI 3 and .NET 8, using Google OAuth for sign-in, local SQLite storage for fast analytics, and optional metadata enrichment services.

Core capabilities

• Google OAuth sign-in with loopback callback and local token persistence
• Dashboard analytics for liked tracks, artists, genres, decades, and playlists
• Rich drill-down views:
  • Liked songs
  • Artists and artist detail
  • Genres and genre detail
  • Decades and decade detail
  • Playlists and playlist detail
• Queue and playback transport controls in the main shell
• Embedded web-based playback surface with global controls
• Local data caching and sync orchestration
• Data export support through export services
• Runtime crash logging support
• Accessibility-oriented UI metadata in XAML controls

Architecture overview

Main layers are organized under src:

• Views: WinUI pages and shell
• ViewModels: UI state and orchestration logic
• Services:
  • AuthService: OAuth flow and token lifecycle
  • YouTubeMusicService: YouTube Data API ingestion
  • YouTubeMusicPrivateClient: optional private endpoint support
  • MusicBrainzService and ExternalMusicMetadataService: enrichment
  • DatabaseService: local persistence and query support
  • PlaybackService: playback state and transport control wiring
  • ExportService: export pipeline
• Models: app/domain data structures
• Helpers: formatting, charts, image and palette utilities
• Themes: app styling resources

Configuration

The app reads configuration from environment variables, and also supports a local .env file. Resolution order is:

1. Process/user/system environment variables
2. .env discovered by walking up from the app base directory

Required values

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET

Optional values

• ENABLE_PRIVATE_YTM
  • true or 1 enables private YouTube Music endpoint mode
  • false or 0 disables it

.env setup

1. Copy .env.example to .env
2. Fill in your own values
3. Keep .env local only (ignored by git)

Example:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
ENABLE_PRIVATE_YTM=false

Security and privacy guidance

• .env and .env.* are ignored by git (except .env.example)
• Do not commit secrets, tokens, or credential exports
• OAuth secrets are loaded at runtime, not hardcoded in source
• Review any local debug/session files before commits

Dependencies

Primary project dependencies in the WinUI project file:

• Microsoft.WindowsAppSDK 2.2.0
• CommunityToolkit.Mvvm 8.4.2
• Microsoft.Data.Sqlite 10.0.9

Build/runtime prerequisites:

• Windows 10/11
• .NET SDK 8.x
• Workloads required for WinUI 3 development

Build and run

From repository root:

dotnet restore src/MusicCurator.csproj
dotnet build src/MusicCurator.csproj -c Debug

Launch after build:

.\run.bat

Release build:

dotnet build src/MusicCurator.csproj -c Release

Repository layout

• src: application source
• assets: shared app assets copied to output
• docs: supplementary documentation
• tools: utility scripts for icon/tile generation
• run.bat: local launch helper

CI/CD

A release workflow is included to build on Windows when a GitHub release is published. It restores dependencies, compiles the project, and uploads build outputs as release artifacts.

Secret-safe repository practices

• Keep only templates in version control (example files)
• Keep working secret files local and ignored
• Use .env.example as the shareable configuration contract
• Never include personal OAuth values in docs, scripts, or fixtures

Troubleshooting

OAuth errors:

• Verify Google OAuth redirect URI matches your configured callback
• Confirm GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are present
• Ensure your OAuth app is configured for desktop/loopback-compatible flow

Build errors:

• Confirm .NET 8 SDK is installed
• Ensure WinUI tooling prerequisites are present
• Run dotnet restore before dotnet build

Versioning

Project version metadata is currently defined in the project file and can be aligned with GitHub releases.

Changelog

v1.7.4

• Fixed queue navigation reliability from the now-playing bar, including open/close toggle behavior.
• Improved now-playing and list artwork rendering so cover art is centered and fills its frame.
• Upgraded queue view layout with a dedicated album column and cleaner row rhythm.
• Made queue artist and album fields clickable for faster drill-down navigation.
• Reduced artist detail load latency by showing local tracks/albums immediately, then hydrating enrichment in the background.
• Made artist names clickable in the Most liked artists chart.
• Stabilized dashboard metrics (liked count and listening-time totals) by deduping on immutable video IDs instead of mutable metadata.

Copyright and license

• Copyright (c) 2026 Mike Hartley / Hart of the Midlands
• Licensed under the repository license terms