Velora Universal

a fork of Flourish0x's Velora music player (found on https://github.com/Flourish0x/Velora) that compiles for macOS, iOS, android, Linux, and Windows

How to build

Requires node.js 20+ Rust (a stable verion, tested cargo versions are 1.98.0 and 1.96.0) Afterwards, run npm install to install project's dependencies

Linux Build instructions

Following instructions assume you are currently using linux to build the linux application.

Dependencies needed

Debian / Ubuntu:

sudo apt update
sudo apt install -y build-essential curl wget file pkg-config git \
  libwebkit2gtk-4.1-dev libxdo-dev libssl-dev \
  libayatana-appindicator3-dev librsvg2-dev libasound2-dev

Fedora:

sudo dnf install webkit2gtk4.1-devel openssl-devel curl wget file libxdo-devel \
  libappindicator-gtk3-devel librsvg2-devel alsa-lib-devel
sudo dnf group install "c-development"

Arch:

sudo pacman -S --needed webkit2gtk-4.1 base-devel curl wget file openssl \
  xdotool libayatana-appindicator librsvg alsa-lib

Build and then run

npm run tauri dev                              # run with hot reload
npm run tauri build                            # all formats valid on this OS
npm run tauri build -- --bundles deb,rpm       # specific formats

Outputs are in src-tauri/target/release/bundle/ (deb/, rpm/, appimage/).

Linux specific notes:

• UI runs in WebkitGTK, not Electron/Chromium, behaviour may differ.
• Any feature that is listed for window (like #[cfg(windows)] in src-tauri/src/lib.rs) will NOT build, I will not add this feature.

macOS Build instructions

Assuming you are using macOS to build the macOS version:

Dependencies

Xcode is needed, to install the command line utilities: xcode-select --install

Build and then run

npm run tauri dev

Universal binary (Intel + Apple Silicon):

rustup target add aarch64-apple-darwin x86_64-apple-darwin
npm run tauri build -- --target universal-apple-darwin

Apple Silicon only: npm run tauri build.

Output: src-tauri/target/universal-apple-darwin/release/bundle/ (macos/Velora.app, dmg/). For a non-universal build the folder is src-tauri/target/release/bundle/. (though these should alr be in the repo since i ran them myself)

macOS notes

• Icon: the bundle requires icon.icns to have an icon, generate with npm run tauri icon path/to/1024x1024.png.
• If shipping, Gatekeeper will make a fuss. (to fix this, the user has to run xattr -cr Velora.app, but for the user to not even encounter this problem, an Apple Developer account is needed for notarization, this build does not support that, please investigate further.)
• The windowing system does not follow macOS's traditional traffic light windows, it uses it's own windowing style.

Android Build instructions

Assuming you are on either macOS or Linux, though Windows should support building android APK's:

Dependencies

• JDK 17
• Android Studio, or the command line tools, with the SDK, platform tools and NDK installed
• Environment variables (adjust paths):

export JAVA_HOME=/path/to/jdk-17
export ANDROID_HOME="$HOME/Library/Android/sdk"          # Linux: ~/Android/Sdk
export NDK_HOME="$ANDROID_HOME/ndk/<installed-version>"

Build instructions

• Generate rust targets:

rustup target add aarch64-linux-android armv7-linux-androideabi \
  i686-linux-android x86_64-linux-android

npm run tauri android init

This creates src-tauri/gen/android/. Commit it. (though these should alr be in the repo since i ran them myself)

Build and then run

npm run tauri android dev

Pick an emulator or a connected device, has only been tested with a QEMU emulator on an Apple Silicon host, ymmv (your mileage may vary) on other hosts or build enviroments.

to get an APK:

npm run tauri android build -- --apk              # release APK
npm run tauri android build -- --apk --debug      # debug APK, installs without signing setup
npm run tauri android build -- --aab              # Play Store bundle

Output: src-tauri/gen/android/app/build/outputs/apk/ (or bundle/).

A release APK must be signed before it installs. Create a keystore and configure signing in src-tauri/gen/android/app/build.gradle.kts (see the Tauri Android signing docs). Never commit the keystore or its passwords.

Android notes

• App has a custom different icon. (I have no clue how to fix this and I didn't really investigate further, if a desired feature, this needs investigating)
• Folder import is desktop only.
• The package name comes from identifier in tauri.conf.json. Changing it makes Android treat the app as a new one.
• Playback on mobile uses blob URLs read from app storage instead of the custom audio protocol. Whole files are held in memory, so very large files are heavy.
• Mobile cannot use the native rfd dialogs or walk folders. On mobile the frontend (src/platform.ts) uses the dialog plugin, reads the picked content:// URI, writes a copy into app data, then calls scan_audio_paths on the real path.
• This has virtually been untested past android 10, newer androids versions SHOULD work, but ymmv.

iOS Build instructions

Assuming you are using a Mac, with the Xcode app opened atleast once:

Dependencies

Xcode command-line utilities (xcode-select --install) and Xcode.app CocoaPods: brew install cocoapods

Build and then run

rustup target add aarch64-apple-ios aarch64-apple-ios-sim

First time run:

npm run tauri ios init

This creates src-tauri/gen/apple/. Commit the sources, not the build output. (though these should alr be in the repo since i ran them myself)

Signing (free Apple ID works)

1. Xcode, Settings, Accounts: sign in with your Apple ID.
2. Open the project: open src-tauri/gen/apple/velora.xcodeproj
3. Select the velora_iOS target, Signing & Capabilities. Enable Automatically manage signing and choose your team.
4. Free accounts need a globally unique bundle ID. If app.velora.player is rejected, change identifier in tauri.conf.json and re-run ios init.
5. Register your phone once. Plug it in, unlock, tap Trust, enable Settings, Privacy & Security, Developer Mode. Then in Xcode choose the phone as the run destination and press Run. This registers the device and creates the provisioning profile. The CLI cannot do this step on its own, because it builds for "Any iOS Device".
6. Put the team in tauri.conf.json:

"bundle": { "iOS": { "developmentTeam": "YOUR_TEAM_ID" } }

The Team ID is not the code in parentheses in a certificate name for a free account. Use the value Xcode writes into DEVELOPMENT_TEAM in src-tauri/gen/apple/velora.xcodeproj/project.pbxproj after you choose the team, or the OU= field from:

security find-certificate -c "Apple Development" -p | openssl x509 -noout -subject

Building notice

IF you are building from the terminal:

• errSecInternalComponent during CodeSign means the keychain key is locked or not accessible from the terminal. Fix:

security unlock-keychain ~/Library/Keychains/login.keychain-db
security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "<mac-login-password>" ~/Library/Keychains/login.keychain-db

If you are getting a complaint that your team has no devices, plug in an iOS device whilst Xcode is running, and select "Trust" on your iOS device.

Building an IPA

npm run tauri ios build -- --export-method debugging

Output: src-tauri/gen/apple/build/arm64/Velora.ipa.

Sideload with your preferred method.

Simulator (no signing)

npm run tauri ios dev

Choose a simulator. Drag mp3 files onto it to save them to Files.

iOS notes

• App has a custom different icon. (I have no clue how to fix this and I didn't really investigate further, if a desired feature, this needs investigating)
• Folder import is desktop only.
• iOS version tested was 27.0.1, I have no idea if older iOS versions work and how low you can go, ymmv.

have fun implementing these patches upstream, kyro!

also, for anyone that ISN'T kyro, this build is frozen on 0.11.0 due to how kyro sent this source to me below is the original project's README.md:

Velora v0.7 — Windows desktop music player

A local music player made with Tauri 2 + React + TypeScript. Runs as an installed Windows application; no localhost server or hosted backend is required in production.

Quick start for the developer (Windows 10 / 11 x64)

Prerequisites: Node.js 20+, Rust, Visual Studio Build Tools (C++ + Windows SDK), WebView2, and internet access on the build computer for the first AI packaging step.

npm install
npm run desktop:dev

New in v0.7: on the first desktop:dev or desktop:installer run, the build script automatically stages the Windows Whisper executable, DLLs, FFmpeg, and a multilingual quantized Whisper model. This first preparation downloads ~175 MB+ of archives and model data and needs additional disk space to extract them. Later builds reuse the staged files. Users of the completed installer don't download or configure AI tools.

To create the normal Windows setup executable:

npm run desktop:installer

Find the output in src-tauri\target\release\bundle\nsis\. The setup includes the AI resources. Do not distribute the bare compiled velora.exe without its bundled resources; use the installer.

If the model preparation fails because of a network or disk problem, the build stops with an error rather than silently creating a no-AI installer. npm run prepare:ai can be run separately if you want to stage only the AI tools. AI source files reside in scripts/prepare-ai.mjs; compiled third-party components go in src-tauri/resources/ai/ (not included in the source-only ZIP).

Users of the installer

1. Install and open Velora.
2. Add a folder and play a song.
3. Click the lyrics button. .lrc lyrics show immediately where available; otherwise local AI analyzes the audio in the background automatically and lines appear when finished.
4. The result is cached in the user profile, so subsequent plays don't need AI analysis.

No API keys, Whisper executable selector, FFmpeg installation, model download, online service, or user configuration are required. AI defaults to enabled and can be disabled in Preferences if a user wants to save CPU time. English translation is optional. Nothing uploads the music to a server.

Not instant AI transcription: The music plays immediately, but generating lyrics for an entire song may take tens of seconds or minutes depending on the CPU. It can be particularly unreliable for singing, distorted vocals, instrumental music, or background noise. Current output uses approximate line/segment timestamps, not exact Spotify-style word highlighting. A pretrained recognizer cannot guarantee official lyrics.

What's included

• Import entire music folders with recursive scanning, or individual files
• Metadata and artwork extraction, folder collections and playlists
• Native Windows local-file audio playback, resizable navigation, full Now Playing view
• Synced lyrics (.lrc) and automatic bundled offline Whisper AI for missing lyrics
• AI runs off the UI thread, one job at a time, and stores .lrc output in the application cache
• About page showing app version and build ID
• NSIS installer configuration

Technical / redistribution notes

• whisper.cpp Windows CPU build b5454 (MIT license): https://github.com/ggml-org/whisper.cpp/releases/tag/b5454
• Multilingual Whisper ggml-base-q5_1.bin (~60 MB, MIT model collection): https://huggingface.co/ggerganov/whisper.cpp/tree/main
• FFmpeg essentials Windows build from Gyan's distribution (GPLv3 build): https://www.gyan.dev/ffmpeg/builds/. Before publicly redistributing Velora with this binary, comply with FFmpeg's GPLv3 and other license requirements (including providing applicable license text and corresponding source). For a proprietary release, replace this with a properly licensed decoder rather than ignoring these requirements.
• Upstream source and license information: https://github.com/ggml-org/whisper.cpp, https://github.com/FFmpeg/FFmpeg, https://github.com/openai/whisper.

The download script verifies the pinned whisper.cpp release archive SHA-256 and checks FFmpeg against the distributor's published SHA-256 when available. The model is downloaded over HTTPS and verified by expected size. For production, pin all dependencies by immutable digest and test both Windows build and installer; this environment cannot perform a Windows compilation.

Known limitations

• This source archive does not contain precompiled Windows AI binaries or an .exe; the developer build retrieves them and includes them in the actual installer.
• Individually imported files are not yet remembered after restarting (folder imports are).
• Albums with uncommon tags may still have metadata gaps.
• First playback of some audio formats may have buffering latency depending on Windows codecs and the user's disk.
• AI lyrics timing is approximate and may require later editing.