Repository: maxrave-dev/SimpMusic

Stars: 8774

CLAUDE.md Copy Chapter

CLAUDE.md - SimpMusic Project Guide for AI Agents

📋 Project Overview Copy Chapter

SimpMusic is a FOSS (Free and Open Source Software) YouTube Music client for Android and Desktop, built with Compose Multiplatform.

Main Purpose Copy Section

Basic Information Copy Section

🏗️ Architecture Copy Chapter

Clean Architecture Layers Copy Section

┌─────────────────────────────────────┐
│  Presentation Layer (UI)            │
│  - Jetpack Compose / Compose MP     │
│  - ViewModels (MVVM)                │
│  - UI States                        │
├─────────────────────────────────────┤
│  Domain Layer                       │
│  - Use Cases                        │
│  - Domain Models                    │
│  - Repository Interfaces            │
├─────────────────────────────────────┤
│  Data Layer                         │
│  - Repository Implementations       │
│  - Data Sources (Remote/Local)      │
│  - Database (Room)                  │
├─────────────────────────────────────┤
│  Service Layer                      │
│  - YouTube Music Scraper            │
│  - Spotify Service                  │
│  - AI Service                       │
│  - Lyrics Service                   │
│  - Discord RPC (Kizzy)              │
└─────────────────────────────────────┘

📁 Module Structure Copy Chapter

Root Modules Copy Section

#### 1. composeApp/
- Shared Compose Multiplatform module - main module containing shared code
- Supports: Android, Desktop (JVM), iOS (future)
- Contains all UI (Compose) and business logic
- Source sets:
- commonMain/: Shared code for all platforms
- androidMain/: Android-specific code
- desktopMain/: Desktop-specific code
- Can run Desktop app directly from this module

#### 2. androidApp/
- Android-specific module to build Android app
- Depends on composeApp as a shared module
- Contains Android-specific configuration:
- AndroidManifest.xml
- Android build configuration
- Android resources (if needed)
- Entry point for Android app

#### 3. core/
Contains core modules organized by functionality:

##### core/common/
- Shared utilities
- Extension functions
- Constants
- Helper classes

##### core/domain/
- Domain models
- Use cases
- Repository interfaces
- Business logic rules

##### core/data/
- Repository implementations
- Data sources (Remote & Local)
- Database schemas (Room)
- Data mappers

##### core/media/
- media3/: Media3 ExoPlayer integration (includes CrossfadeExoPlayerAdapter for DJ-style crossfade on Android)
- media3-ui/: Media3 UI components
- media-jvm/: JVM media playback (VLCJ - replaced GStreamer post-1.0.4)
- media-jvm-ui/: JVM media UI components

##### core/service/
Service modules:

- kotlinYtmusicScraper/: YouTube Music API scraper
- spotify/: Spotify Web API integration (Canvas, Lyrics)
- aiService/: AI features (OpenAI, Gemini integration)
- lyricsService/: Lyrics fetching (LRCLIB, SimpMusic Lyrics, BetterLyrics)
- kizzy/: Discord Rich Presence
- ktorExt/: Ktor extensions for networking

#### 4. crashlytics/ & crashlytics-empty/
- crashlytics/: Full version with Sentry crash reporting
- crashlytics-empty/: FOSS version without tracking

🛠️ Key Technologies Copy Chapter

Android/Mobile Copy Section

Desktop Copy Section

Networking & APIs Copy Section

Data & Storage Copy Section

Third-party Integrations Copy Section

📝 Development Guidelines Copy Chapter

Code Style Copy Section

Module Dependencies Copy Section

UI Layer (composeApp)
    ↓
Domain Layer (core/domain)
    ↓
Data Layer (core/data)
    ↓
Service Layer (core/service/*)
    ↓
Common (core/common)

Dependency Rule: Higher layer modules can only depend on lower layer modules, NOT vice versa.

Working with UI Copy Section

Working with Data Copy Section

Research Before Implementation (MANDATORY) Copy Section

Before implementing code, researching code, or answering technical questions, the AI agent MUST follow this research workflow:

#### Step 1: Look up official documentation
- Use MCP Context7 (resolve-library-id → query-docs) to fetch up-to-date documentation for any library/framework about to be used
- Understand the latest API surface, breaking changes, and recommended usage patterns

#### Step 2: Evaluate pros, cons, and alternatives
- Use WebSearch to research:
- Pros and cons of the library/approach
- Alternative libraries or approaches that solve the same problem
- Known issues, performance concerns, or deprecation notices
- Compare and evaluate whether the chosen library/approach is the best fit for this project

#### Step 3: Study OSS best practices
- Use Grep (on GitHub via web search) or WebSearch to find how well-known open-source projects implement similar features
- Verify the approach follows established best practices before adopting it
- Pay attention to patterns used in projects with similar architecture (Clean Architecture, Compose Multiplatform, etc.)

#### Step 4: Make a decision and justify
- Only proceed with implementation after completing steps 1-3
- If a library/approach has significant drawbacks or better alternatives exist, recommend the better option to the user before proceeding
- Document the rationale briefly when introducing new dependencies or patterns

This workflow applies to: Adding new libraries, choosing architectural patterns, implementing new features with unfamiliar APIs, answering "how should we do X?" questions, and evaluating technical approaches.

This workflow does NOT apply to: Simple bug fixes in existing code, minor refactoring, or tasks using libraries already well-established in the project.

Verification After Code Changes Copy Section

Testing Copy Section

🎯 Common Tasks Copy Chapter

1. Add New UI Feature Copy Section

2. Add New API Endpoint Copy Section

3. Add New Database Entity Copy Section

4. Add New Use Case Copy Section

5. Work with Media Playback Copy Section

6. Add New Lyrics Provider Copy Section

7. AI Features Copy Section

📍 Important Files and Locations Copy Chapter

Configuration Copy Section

Main Application Copy Section

Database Copy Section

Network Copy Section

Resources Copy Section

🔧 Build Variants Copy Chapter

Android Copy Section

Desktop Copy Section

🚨 Important Notes Copy Chapter

Privacy & Data Collection Copy Section

Platform-specific Considerations Copy Section

#### Android
- Min SDK: Check androidApp/build.gradle.kts
- Target SDK: Latest stable
- Android Auto support
- Background playback with MediaSession

#### Desktop
- Required Dependencies:
- VLCJ: Audio playback (bundled via vlc-setup plugin)
- Features:
- Deep link support (simpmusic:// and simpmusic.org)
- Mini Player window (always-on-top, resizable, draggable)
- Crash dialog
- Custom title bar (disabled in VM environments)
- Limitations:
- No offline playback
- No video playback

External APIs Copy Section

🎵 Media Playback Architecture Copy Chapter

Desktop Player (VLCJ - replaced GStreamer post-1.0.4) Copy Section

Location: core/media/media-jvm/src/main/java/com/simpmusic/media_jvm/VlcPlayerAdapter.kt

- Uses VLCJ library for audio playback (GStreamer was removed)
- VLC native libraries bundled per platform via vlc-setup Gradle plugin in composeApp/build.gradle.kts
- Bundled natives stored in vlc-natives/{linux,macos,windows}/
- Supports crossfade transition with dual-player approach

#### Crossfade Transition (Desktop)
- Configurable duration: 1-15 seconds (default: 5 seconds)
- Audio-only: Crossfade is skipped for video playback
- Settings persisted via DataStore

Android Player (Media3/ExoPlayer) Copy Section

#### Crossfade & DJ-style Transition (added in v1.0.4)

Location: core/media/media3/src/main/java/com/maxrave/media3/exoplayer/CrossfadeExoPlayerAdapter.kt

- DJ-style crossfade with adjustable duration
- Requires 320kbps stream preference to enable DJ mode
- Auto crossfade mode (like AutoMix)
- CrossfadeFilterAudioProcessor for audio processing
- Edge cases: disabled for video, repeat one, last track

🤝 Contributing Copy Chapter

Code of Conduct Copy Section

Pull Request Guidelines Copy Section

Translation Copy Section

📚 References Copy Chapter

Inspiration & Credits Copy Section

External Documentation Copy Section

Community Copy Section

---

🎯 Quick Start for AI Agents Copy Chapter

When working with this project:

1. Always check layer dependencies: Don't violate Clean Architecture rules
2. Use existing patterns: Review current code to follow established patterns
3. Platform-aware: Code in commonMain must work for both Android and Desktop
4. Test thoroughly: Especially critical for media playback and network code
5. Consider privacy: FOSS version must NOT have tracking
6. Check external API stability: YouTube Music API may change at any time

When Encountering Issues Copy Section

Platform-Specific Code Patterns Copy Section

Example: Desktop-only UI settings

if (getPlatform() == Platform.Desktop) {
    // Desktop-specific UI or logic
}

Example: Android-only features

if (getPlatform() == Platform.Android) {
    // Android-specific UI or logic
}

📜 Changelog Summary (post-1.0.4) Copy Chapter

Architecture Changes Copy Section

New Features (v1.0.4) Copy Section

New Features (v1.0.1 - v1.0.3) Copy Section

New Features (post-1.0.4, dev branch) Copy Section

🔄 CLAUDE.md Auto-Update Rule (MANDATORY) Copy Chapter

After completing any of the following types of changes, the AI agent MUST update this CLAUDE.md file:

1. Architecture changes: Module additions/removals, dependency changes (e.g., library swaps like GStreamer → VLCJ), build system changes
2. New major features: New modules, new service integrations, new platform capabilities
3. API/Technology migrations: Swapping core libraries, changing data flow patterns
4. Build/CI changes: New build variants, changed packaging formats, CI workflow changes
5. Module structure changes: Adding/removing modules in settings.gradle.kts

What to update:
- Relevant sections in this document (Module Structure, Key Technologies, etc.)
- Add entry to Changelog Summary section with date/version context
- Update "Last updated" date at the bottom

What NOT to update for:
- Bug fixes, minor UI tweaks, translation updates
- Simple refactoring within existing patterns
- Dependency version bumps without API changes

---

This document helps AI Agents quickly understand the SimpMusic project. Update regularly when there are major changes to architecture or structure.

Last updated: 2026-03-14
Project version: Check latest release on GitHub
Maintained by: maxrave-dev and contributors

README.md Copy Chapter

<div align="center"> <img src="https://raw.githubusercontent.com/maxrave-dev/SimpMusic/main/fastlane/metadata/android/en-US/images/featureGraphic.png"> <h1>SimpMusic</h1>
A FOSS YouTube Music client for Android and Desktop with many features from<br>Spotify, SponsorBlock, ReturnYouTubeDislike using Compose Multiplatform to develop.
<br>
<br>
<a href="https://github.com/maxrave-dev/SimpMusic/releases"><img src="https://img.shields.io/github/v/release/maxrave-dev/SimpMusic"></a> <a href="https://github.com/maxrave-dev/SimpMusic/releases"><img src="https://img.shields.io/github/downloads/maxrave-dev/SimpMusic/total"></a> <br> <br> <a href="https://trendshift.io/repositories/13482" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13482" alt="maxrave-dev%2FSimpMusic | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
<br>
<br>
<a href="https://www.producthunt.com/products/simpmusic/reviews?utm_source=badge-product_rating&utm_medium=badge&utm_source=badge-simpmusic" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/product_rating.svg?product_id=903836&theme=dark" alt="SimpMusic - A&#0032;FOSS&#0032;YouTube&#0032;Music&#0032;client&#0032;for&#0032;Android&#0032;with&#0032;many&#0032;features | Product Hunt" style="width: 242px; height: 108px;" width="242" height="108" /></a>
<br>
<h4>Download</h4>
<a href="https://apt.izzysoft.de/packages/com.maxrave.simpmusic/"><img src="https://gitlab.com/IzzyOnDroid/repo/-/raw/master/assets/IzzyOnDroid.png" width="200"></a>
<a href="https://f-droid.org/en/packages/com.maxrave.simpmusic/"><img src="https://fdroid.gitlab.io/artwork/badge/get-it-on.png" width="200"></a>
<a href="https://www.openapk.net/simpmusic/com.maxrave.simpmusic/"><img src="https://www.openapk.net/images/openapk-badge.png" width="200"></a>
<a href="https://github.com/maxrave-dev/SimpMusic/releases"><img src="https://raw.githubusercontent.com/NeoApplications/Neo-Backup/034b226cea5c1b30eb4f6a6f313e4dadcbb0ece4/badge_github.png" width="200"></a>
<h4>Nightly Build</h4>
<a href="https://simpmusic.org/nightly-download"><img src="https://github.com/maxrave-dev/SimpMusic/actions/workflows/android.yml/badge.svg"></a><br/> <a href="https://simpmusic.org/nightly-download"><img src="https://raw.githubusercontent.com/NeoApplications/Neo-Backup/034b226cea5c1b30eb4f6a6f313e4dadcbb0ece4/badge_github.png" width="200"></a>
</div>

SimpMusic is available on Desktop now!

Features ✨️ Copy Chapter

(\*) Use your OpenAI or Gemini API key

(\) For users who chose "Send back to Google" feature

Warning

please create an issue or contact me via email or Discord server.

Because of depending on YouTube Music, the player error will happen and it's normally, please don't ask me about the stable state of this app.

Screenshots Copy Chapter

#### More screenshots here.

## Data
- This app uses hidden API from YouTube Music with some tricks to get data from YouTube Music.
- Use Spotify Web API and some tricks to get Spotify Canvas and Lyrics
- Thanks to InnerTune for the idea to get data from YouTube Music. This repo is my inspiration to create this app.
- Special thanks to SmartTube. This repo help me to extract the streaming URL of YouTube Music.
- My app is using SponsorBlock to skip sponsor in YouTube videos.
- ReturnYouTubeDislike for getting information on votes
- Main lyrics data from SimpMusic Lyrics
- Alternative lyrics data from LRCLIB. More information LRCLIB

## Privacy
SimpMusic doesn't have any tracker or third-party server for collecting user data in FOSS version. If YouTube
logged-in users enable "Send back to Google" feature, SimpMusic only uses YouTube Music Tracking API to send listening history and listening record of video to Google for better recommendations and
supporting artist or YouTube Creator (For API reference,
see this).

We collect crash data in the Full version to improve the app.

Full or FOSS version Copy Chapter

Desktop app Copy Chapter

Which file should I download? Copy Section

Log in guide: https://www.simpmusic.org/blogs/en/how-to-log-in-on-desktop-app Copy Section

Some limitations on Desktop app: Copy Section

Please report issues on our Discord server if you find any bugs.

Translation Copy Chapter

Legal Disclaimer & Terms of Use Copy Chapter

1. 100% Free, Open-Source & Strictly Non-Commercial Copy Section

2. A Custom Browser with Content Filtering Copy Section

3. Support Content Creators Copy Section

4. No Hosting of Copyrighted Material Copy Section

5. User Responsibility & Legal Contact Copy Section

Because we do not host any media files, we cannot process DMCA takedown requests for audio or video content. However, if you represent a copyright holder or have legal concerns regarding the open-source code itself, please contact us via email at: [email protected]

## Contribute
We're looking for more contributors, all contributions are welcome!
See our CODE OF CONDUCT

Thanks for all my contributors:

<a href="https://github.com/maxrave-dev/SimpMusic/graphs/contributors">
<img src="https://contrib.rocks/image?repo=maxrave-dev/SimpMusic" />
</a>

## Showcase
This project is following clean architecture and MVVM pattern (in UI, app module).

### Dependencies graph
<p float="left">
<img src="https://github.com/maxrave-dev/SimpMusic/blob/main/asset/dependencies_graph.svg?raw=true" width="800">
</p>

## Support & Donations
#### Special thanks to all supporter ❤️
<div align="left">
<a href="https://simpmusic.org/"><img alt="Visit the website" height="50" src="https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/documentation/website_vector.svg"></a> &nbsp;
<a href="https://discord.gg/Rq5tWVM9Hg"><img alt="Discord Server" height="50" src="https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/social/discord-plural_vector.svg"></a> &nbsp;
<br> <a href="https://www.buymeacoffee.com/maxrave"><img alt="Buy me a Coffee" height="50" src="https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/donate/buymeacoffee-singular_vector.svg"></a> &nbsp;
<a href="https://liberapay.com/maxrave/"><img alt="liberapay" height="50"
src="https://raw.githubusercontent.com/liberapay/liberapay.com/master/www/assets/liberapay/logo-v2_black-on-yellow.svg"></a>
</div>

### MOMO or Vietnamese banking
<p float="left">
<img src="https://github.com/maxrave-dev/SimpMusic/blob/dev/asset/52770992.jpg?raw=true" width="300">
</p>

SimpMusic is sponsored by: Copy Chapter

Get a free $200 credit over 60 days on DigitalOcean: GET NOW

Crowdin and Sentry both have a free enterprise plan for Open-source projects. Follow the URLs:
- Open Source License Request Form | Crowdin
- Sentry for Open Source | Sentry

Check out the Vercel open-source program:
- https://vercel.com/open-source-program

This project is tested with BrowserStack
- Checkout BrowserStack now: https://www.browserstack.com/

This project is a part of SimpMusic.org Open-source project by me maxrave-dev

<!-- GitAds-Verify: 9788276LHF131ESPL12SWLJ8LACOJE89 -->