Development

Development

This page contains the essential information for building, testing and contributing to Levyra.

Levyra contains two native application targets:

• Android — Kotlin, Jetpack Compose and AndroidX Media3 / ExoPlayer
• Windows — Kotlin, Compose Multiplatform and libvlc

---

Repository

Clone the official repository:

git clone https://github.com/LUC4N3X/Levyra-deepsound.git
cd Levyra-deepsound

Repository:

github.com/LUC4N3X/Levyra-deepsound

---

Android development

Requirements

The current Android build requires:

• JDK 17
• Android SDK Platform 37
• Gradle 9.7.0
• Android Studio or a compatible Android development environment

The repository includes the Gradle Wrapper, so a separate Gradle installation is normally not required.

---

Build a debug version

Linux / macOS

./gradlew assembleDebug

Windows

.\gradlew.bat assembleDebug

The generated APK can be found under:

app/build/outputs/apk/debug/

---

Install directly on a connected Android device

Enable Developer Options and USB debugging on the Android device, connect it to the computer and run:

Linux / macOS

./gradlew installDebug

Windows

.\gradlew.bat installDebug

ADB should detect the device before installation.

You can verify this with:

adb devices

---

Build the Android release

Linux / macOS

./gradlew clean assembleRelease

Windows

.\gradlew.bat clean assembleRelease

Release output:

app/build/outputs/apk/release/app-release.apk

Release signing requirements may differ from local debug builds.

---

Windows development

Levyra Desktop uses its own native desktop playback stack.

Requirements

• Windows x64
• JDK 21 LTS
• VLC 3.0.x / libvlc
• WiX Toolset 3.14

Enter the desktop project:

cd desktop

Run validation:

.\gradlew.bat check

Create the release distributable:

.\gradlew.bat createReleaseDistributable

Build the Windows packages:

.\gradlew.bat packageReleaseMsi packageReleaseExe

Generated desktop artifacts are placed under:

desktop/app/build/compose/binaries/main-release/

---

Project structure

Some of the main areas of the repository are:

app/
├── src/main/java/com/luc4n3x/levyra/
│   ├── ui/
│   ├── viewmodel/
│   ├── player/
│   └── data/

desktop/
├── app/
├── player/
├── core/
└── packaging/

baselineprofile/
docs/
scripts/
levyra-recognition/

Android

ui/ : Jetpack Compose screens and visual presentation.

viewmodel/ : UI state and application coordination.

player/ : Media3 / ExoPlayer playback, MediaSession and playback services.

data/ : Data access, stream resolution, lyrics and persistent data.

Windows

desktop/app/ : Desktop UI and application lifecycle.

desktop/player/ : libvlc playback engine.

desktop/core/ : Desktop stream resolution, downloads and application storage.

desktop/packaging/ : Windows packaging and distribution.

---

Development workflow

Create a focused branch from the latest main:

git checkout main
git pull
git checkout -b feature/your-feature-name

Keep each pull request focused on a single concern whenever possible.

---

Code quality

Before opening a pull request, run the repository quality gate:

python scripts/ai_quality_gate.py --profile fast

Also build and test the affected platform.

For Android changes, testing on a real Android device is strongly recommended when the change affects:

• Playback
• MediaSession
• Background behavior
• Downloads
• Local files
• Audio
• Permissions
• Performance
• Device-specific UI behavior

---

Architecture principles

Changes should preserve the main engineering principles used by Levyra:

• Unidirectional data flow
• Predictable state ownership
• Immutable Compose UI state where appropriate
• Low-latency playback paths
• Local-first user data
• Minimal unnecessary main-thread work
• Resilient playback and stream resolution
• Platform-native behavior where Android and Windows differ

---

Pull requests

A good pull request should include:

• A clear description of the problem
• What was changed
• Why the chosen approach was used
• Testing performed
• Screenshots or recordings for visual changes
• Relevant issue links when applicable

For large features or architectural changes, opening an Issue before implementation is recommended.

Open an Issue

View Pull Requests

---

License

Levyra is distributed under the GNU General Public License v3.0.

Contributions to the project must remain compatible with the project's license and third-party licensing requirements.

View the License

---

← Back to Home