QVeats is a desktop-first local AI music studio. It uses QVAC by Tether for both instruction-tuned lyric writing and complete ACE-Step song generation. It does not call another AI provider, a hosted inference API, or mocked audio.

QVeats has been vibecoded and is an experimental personal project intended primarily as a showcase of QVAC's local music-generation capabilities. It is not production-ready software and may contain bugs, incomplete safeguards, breaking changes, or performance and reliability issues. Use it at your own risk, and do not depend on it for critical workflows or irreplaceable data.

• Node.js 22.17 or later and npm 10.9 or later
• macOS 14+ (Apple silicon recommended; Intel uses CPU inference), Ubuntu 22+ on arm64/x64, or Windows 10+ on x64
• Vulkan 1.4 on Linux and Windows; Metal is used on Apple silicon
• 8 GB RAM recommended (4 GB is the minimum check)
• At least 7 GB free disk space for model files and download overhead

QVAC currently falls back to CPU on Linux when Vulkan is unavailable. Windows requires Vulkan even for CPU inference. Song generation is compute-heavy and may be slow on lower-end or CPU-only hardware.

npm install
npm start

npm start builds the React renderer, Electron main/preload processes, and the selected QVAC SDK worker bundle before launching the app. The installed Node version is checked by npm through package.json.

For UI-only development, use npm run dev. For the full trusted desktop runtime, QVAC integration, file persistence, and playback, use npm start.

qvac.config.json enables only the capabilities used by QVeats:

{
  "plugins": [
    "@qvac/sdk/llamacpp-completion/plugin",
    "@qvac/sdk/audiogen-ggml/plugin"
  ],
  "registryStreamTimeoutMs": 600000,
  "registryDownloadMaxRetries": 10
}

Build the SDK bundle independently with:

npm run bundle:qvac

The generated qvac/worker.bundle.js, worker entry, and addon manifest target supported desktop hosts. Electron/Node uses QVAC’s native Node worker; the same configuration path is set before the SDK is imported.

The music pipeline uses the required ACE-Step stages:

• AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0 — text encoder
• AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0 — language model
• AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M — DiT
• AUDIOGEN_VAE_BF16 — VAE

These total about 3.28 GB in the current QVAC registry. QVeats shows the combined music and lyric model size, available disk space, platform warnings, and an explicit confirmation before starting the initial download. Each model has live downloaded/total byte progress. Interrupted downloads are resumable through QVAC, and failures expose a retry action.

Lyric creation uses the instruction-tuned QWEN3_4B_INST_Q4_K_M QVAC model, adding about 2.50 GB for roughly 5.77 GB of models in total. QVeats downloads it during initial setup, unloads it after writing, and unloads AudioGen after each render to release memory.

Advanced settings also include a Full song brief field for single-prompt creation. A structured Markdown brief can define the music direction, timed structure, story, hook, and overall feeling in one place. Supported duration, BPM, language, male/female voice, and built-in genre names are detected automatically; the complete brief then drives both lyric writing and music generation.

You can also choose Your own lyrics when starting a session. Paste plain or sectioned lyrics, optionally include a TITLE: line, review the normalized structure and duration fit, then send those lyrics directly to ACE-Step without running the lyric-writing model.

Generated WAV files are written under Electron’s application-data directory:

• macOS: ~/Library/Application Support/QVeats/songs/audio/
• Windows: %APPDATA%/QVeats/songs/audio/
• Linux: ~/.config/QVeats/songs/audio/

Small metadata records are stored separately in songs/songs.json. WAV bytes are never stored in browser local storage. Use Download WAV to copy a song to another location.

Your music is generated locally on your device with QVAC. QVeats has no account, cloud database, analytics, telemetry, or cloud inference. Prompts prohibit copying recognizable lyrics, melodies, vocal identity, signature phrases, and recordings.

npm test
npm run build
npm run package

The test suite covers validation, searchable style selection, caption construction, vocal voice and language controls, instrumental parameters, lyric parsing, PCM-to-WAV conversion across supported sample widths, targeted cancellation, persistence, object URL cleanup, and recovery after failures.

• The first run requires a network connection to obtain QVAC registry models. Inference is local after models are cached.
• ACE-Step rounds requested duration to its internal frame grid, so the result can differ slightly from 15/30/60/90 seconds. QVeats displays duration reported by QVAC or calculated from actual PCM frames.
• AudioGen generation is intentionally single-flight; only one active request is allowed.
• Hardware/driver diagnostics can identify common unsupported configurations, but some model-loading failures can only be detected when QVAC initializes the native backend.
• Packaging and code-signing credentials are platform-specific and are not included.

QVeats is licensed under the Apache License 2.0.