Kava

Kava is a Windows desktop app for analyzing media links, downloading audio or video, organizing a local media library, converting files, and playing audio directly inside the app.

The project is built with Tauri, React, TypeScript, and a local Rust backend. It uses yt-dlp for URL analysis and downloads, ffmpeg / ffprobe for conversion and media inspection, and mpv for integrated audio playback.

View the latest GitHub release

This README describes the repository as it is wired today. It should not be read as a roadmap.

The Downloads page lets users paste a URL, analyze it, choose standard or expert mode, and follow progress in a backend-managed download queue.

Expert mode exposes the available formats returned by yt-dlp. It lets users choose a specific video stream, a compatible audio stream, or a progressive format when the source provides one.

The Library brings together downloaded files and local folders added by the user. It supports search, filters, playlists, custom folders, and integrated audio playback.

• Analyze media URLs with yt-dlp.
• Download audio or video through a real backend queue.
• Pause, resume, cancel, or remove downloads.
• Download a full playlist or only selected playlist items.
• Choose a simple quality preset in standard mode or a precise format in expert mode.
• Organize media in a local library with search and filters.
• Create local playlists and associate files with custom folders.
• Load the library quickly from a SQLite snapshot, then resynchronize in the background.
• Convert files with ffmpeg to common audio and video formats.
• Play audio inside the app with an mpv backend and an integrated playback bar.
• Inspect runtime diagnostics for yt-dlp, ffmpeg, and mpv.
• Open the main window maximized and use a compact Windows-aware mini-player.

Implemented today:

• real URL analysis and downloads through yt-dlp;
• backend-normalized source support for YouTube, SoundCloud, TikTok, Twitch, Instagram, Twitter/X, RSS, and unknown sources;
• persistent download queue with progress updates;
• local library with SQLite cache, playlists, folders, and optimistic UI deletion;
• virtualized library list with react-virtuoso;
• media conversion through ffmpeg;
• audio playback through mpv;
• runtime diagnostics;
• Windows packaging through Tauri with NSIS and MSI targets.

Important limitations:

• the license system is local and mocked, using test key prefixes such as LIFE-, MONTH-, and FREE-;
• the free quota is calculated but not yet enforced as a download-time blocker;
• cookiesProfile exists in some payloads but is not wired end to end into the yt-dlp commands;
• the app update check is still a stub that essentially returns up_to_date;
• libVLC resources still exist in the repository, but the active player is mpv;
• the Settings UI exposes only part of the stored preferences;
• the repository does not currently include a maintained automated test suite.

1. Open Kava.
2. Paste a media URL in the Downloads tab.
3. Choose standard or expert mode.
4. Select the output type: audio or video.
5. Start the download.
6. Find the file in the Library.
7. Play audio in Kava, open video with the system media player, or convert the file if needed.

• React 18
• TypeScript
• Vite
• Tailwind CSS
• Radix UI
• Zustand
• Framer Motion
• i18next / react-i18next
• react-hook-form
• react-hotkeys-hook
• TanStack Table
• react-virtuoso
• sonner

• Tauri 1.x
• Rust
• Tokio
• Rusqlite with bundled SQLite
• Serde / serde_json
• Tracing
• Walkdir
• Windows-specific helpers to avoid visible consoles in release builds

• yt-dlp: URL analysis, available formats, downloads, playlists.
• ffmpeg / ffprobe: inspection, post-processing, thumbnails, conversion.
• mpv: integrated audio playback.

Kava stores local state in SQLite, notably in kava.db under the application data directory.

Important tables:

• downloads
• download_meta
• library_cache
• library_playlists
• library_folders
• conversions
• prefs
• license
• thumbnails
• feeds

The real mounted application entry points are:

• src/main.tsx
• src/App.tsx
• src/pages/Downloads/DownloadsPage.tsx
• src/pages/Library/LibraryPage.tsx
• src/pages/Settings/SettingsPage.tsx

Core backend modules:

• src-tauri/src/main.rs
• src-tauri/src/commands/mod.rs
• src-tauri/src/worker.rs
• src-tauri/src/conversion.rs
• src-tauri/src/player.rs
• src-tauri/src/runtime.rs
• src-tauri/src/db.rs
• src-tauri/src/state.rs
• src-tauri/src/diagnostics.rs

The src/features/* directory still contains older or partially reused components. It should not be treated as the source of truth for the UI currently shown by the app.

Install dependencies:

npm install

Run the frontend only:

npm run dev

Run the full native Tauri app on Windows:

Set-Location <path-to-repo>
npm install
npx tauri dev

When working from WSL, use a Windows checkout of the repository to validate the native app. A Linux node_modules directory does not contain the native Windows binaries required by Tauri and Rollup.

Useful WSL command:

cmd.exe /C "cd /d <windows-repo-path> && npx tauri dev"

• npm run dev: start Vite.
• npm run build: compile TypeScript and build the frontend.
• npm run preview: preview the frontend build.
• npm run lint: run ESLint on src.
• npm run format: format src/**/*.{ts,tsx,css} with Prettier.
• npm run tauri: proxy to the Tauri CLI.
• npm run setup:wsl: prepare WSL development helpers.
• npm run build:windows-installer: build the Windows installer through the dedicated script.

Standard Tauri build:

npm run build
npx tauri build

Build through the repository script:

npm run build:windows-installer

The Tauri configuration currently targets NSIS and MSI, with productName set to Kava and identifier com.kava.desktop.

• Always check src/App.tsx and the mounted pages before concluding that a feature is active.
• Treat mpv as the real player wired today.
• Do not present licensing, payments, free quota enforcement, or auto-update as finalized systems.
• For UI changes, validate the rendering in the native Tauri app when possible.
• For mini-player or Windows windowing bugs, check both the frontend code and the native window_set_mini_player_chrome command.

• AGENTS.md: detailed snapshot of the real project state.
• docs/architecture.md: technical application structure.
• docs/windows-packaging.md: Windows packaging notes.