mirror of
https://github.com/spalencsar/bearwave.git
synced 2026-07-07 22:54:15 +02:00
Refine README for public GitHub presentation
This commit is contained in:
Sebastian Palencsar
306
README.md
306
README.md
@@ -1,34 +1,87 @@
|
|||||||
# BearWave
|
# BearWave
|
||||||
|
|
||||||
BearWave is a desktop internet radio player for KDE Plasma, built with C++/Qt 6, QML, KDE Frameworks, and Phonon.
|
KDE-focused desktop internet radio app for Linux, built with Qt 6, QML, KDE Frameworks, and Phonon.
|
||||||
|
|
||||||
It is designed for fast station browsing, simple playback controls, and good integration into the Plasma desktop experience.
|
BearWave is designed for fast station browsing, simple playback controls, favorites, resume support, tray behavior, and clean Plasma integration without turning into a heavy media suite.
|
||||||
|
|
||||||
BearWave currently targets Linux desktop environments, with KDE Plasma as the primary focus.
|
[](https://github.com/spalencsar/bearwave/actions/workflows/build.yml)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Screenshots
|
## Screenshots
|
||||||
|
|
||||||
|
| Main window | Station browser |
|
||||||
|
| --- | --- |
|
||||||
|
|  |  |
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Highlights
|
Screenshots: KDE Plasma on Linux.
|
||||||
|
|
||||||
- Internet radio via the Radio Browser API (with ultra-fast local JSON caching)
|
---
|
||||||
- Station pages for Top, Germany, Netherlands, and global/genre filters
|
|
||||||
- Real-time local search and filtering (name, genre, country)
|
## Quick Start
|
||||||
- Sorting (name, bitrate, votes)
|
|
||||||
- Favorites with persistent local storage
|
Two sensible paths right now:
|
||||||
- Manual station add
|
|
||||||
- Playback controls and metadata display (title/artist when available)
|
### Option A: Arch Linux
|
||||||
- Resume support for last station and volume
|
|
||||||
- MPRIS integration (Plasma media controls, media keys, media applets with cover art fallback)
|
Use the included `PKGBUILD`:
|
||||||
- System Tray integration for seamless background playback
|
|
||||||
- About dialog with project links and embedded MIT license text
|
```bash
|
||||||
|
makepkg -si
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option B: Local source build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
|
||||||
|
cmake --build build -j"$(nproc)"
|
||||||
|
cmake --install build --prefix "$HOME/.local"
|
||||||
|
```
|
||||||
|
|
||||||
|
Then launch:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
~/.local/bin/bearwave
|
||||||
|
```
|
||||||
|
|
||||||
|
## What BearWave Is
|
||||||
|
|
||||||
|
BearWave focuses on:
|
||||||
|
|
||||||
|
- KDE-first internet radio playback
|
||||||
|
- fast browsing via the Radio Browser API
|
||||||
|
- favorites and resume support
|
||||||
|
- lightweight desktop integration through tray + MPRIS
|
||||||
|
- straightforward local installation and operation
|
||||||
|
|
||||||
|
BearWave intentionally does not aim to be:
|
||||||
|
|
||||||
|
- a local music library manager
|
||||||
|
- a podcast client
|
||||||
|
- a broad cross-platform media application
|
||||||
|
- a feature-heavy all-purpose audio suite
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- internet radio via the Radio Browser API with local JSON caching
|
||||||
|
- station pages for Top, Germany, Netherlands, and quick world/genre filters
|
||||||
|
- local search and filtering by name, genre, and country
|
||||||
|
- sorting by name, bitrate, and votes
|
||||||
|
- favorites with persistent local storage
|
||||||
|
- manual station add
|
||||||
|
- playback metadata display when streams provide it
|
||||||
|
- resume support for last station and volume
|
||||||
|
- MPRIS integration for Plasma media controls and media keys
|
||||||
|
- system tray integration for background playback
|
||||||
|
- embedded About dialog with links and MIT license text
|
||||||
|
|
||||||
## Project Status
|
## Project Status
|
||||||
|
|
||||||
BearWave is a source-first desktop project in an early public stage.
|
BearWave is an early public, source-first desktop project.
|
||||||
|
|
||||||
It is already usable, but it should currently be treated as software for testers, contributors, and technically comfortable Linux users rather than a polished end-user release.
|
It is already usable, but it should currently be treated as software for testers, contributors, and technically comfortable Linux users rather than a polished end-user release.
|
||||||
|
|
||||||
@@ -45,16 +98,16 @@ Current distribution status:
|
|||||||
- Arch Linux is the best-supported packaging path at the moment
|
- Arch Linux is the best-supported packaging path at the moment
|
||||||
- no official Flatpak, AppImage, or broad distro release pipeline yet
|
- no official Flatpak, AppImage, or broad distro release pipeline yet
|
||||||
|
|
||||||
## Target Platform
|
## Platform And Support
|
||||||
|
|
||||||
BearWave is intentionally KDE-first.
|
BearWave is intentionally KDE-first.
|
||||||
|
|
||||||
- primary desktop target: KDE Plasma 6
|
|
||||||
- primary platform target: Linux
|
- primary platform target: Linux
|
||||||
|
- primary desktop target: KDE Plasma 6
|
||||||
- primary development environment: Arch Linux
|
- primary development environment: Arch Linux
|
||||||
- other Linux distributions may build from source, but are not yet documented or tested to the same level
|
- other Linux distributions may build from source, but are not yet documented or tested to the same level
|
||||||
|
|
||||||
## Tested On
|
### Tested On
|
||||||
|
|
||||||
BearWave is currently aligned with and tested primarily against:
|
BearWave is currently aligned with and tested primarily against:
|
||||||
|
|
||||||
@@ -66,7 +119,7 @@ BearWave is currently aligned with and tested primarily against:
|
|||||||
|
|
||||||
If support for other distributions becomes reliable, they should be added here explicitly instead of implied.
|
If support for other distributions becomes reliable, they should be added here explicitly instead of implied.
|
||||||
|
|
||||||
## Language Support
|
### Language Support
|
||||||
|
|
||||||
The current application UI is primarily in German.
|
The current application UI is primarily in German.
|
||||||
|
|
||||||
@@ -74,43 +127,21 @@ The current application UI is primarily in German.
|
|||||||
- README, repository metadata, and development-facing material are in English
|
- README, repository metadata, and development-facing material are in English
|
||||||
- full localization support is not implemented yet
|
- full localization support is not implemented yet
|
||||||
|
|
||||||
If you open the project expecting a fully translated multi-language UI, that is not the current state yet.
|
If you expect a fully translated multi-language UI, that is not the current state yet.
|
||||||
|
|
||||||
## Tech Stack
|
## Installation Status
|
||||||
|
|
||||||
- **Language:** C++
|
BearWave should currently be understood as:
|
||||||
- **UI:** QML (`QtQuick`, `QtQuick.Controls`, `QtQuick.Layouts`)
|
|
||||||
- **Frameworks:** Qt 6, KDE Frameworks 6 (Kirigami where available)
|
|
||||||
- **Audio:** Phonon4Qt6 backend (e.g. VLC backend)
|
|
||||||
- **Networking:** `QNetworkAccessManager` against Radio Browser
|
|
||||||
- **Build system:** CMake
|
|
||||||
|
|
||||||
## Project Layout
|
- officially documented for source builds
|
||||||
|
- most naturally aligned with Arch Linux packaging
|
||||||
|
- likely portable to other Linux distributions with Qt 6 / KF6 / Phonon packages available
|
||||||
|
- not yet positioned as a broadly packaged consumer desktop app
|
||||||
|
|
||||||
```text
|
If you want the least surprising path today, use either:
|
||||||
bearwave/
|
|
||||||
CMakeLists.txt
|
|
||||||
LICENSE
|
|
||||||
README.md
|
|
||||||
org.kde.bearwave.desktop.in
|
|
||||||
src/
|
|
||||||
main.cpp
|
|
||||||
radiobackend.*
|
|
||||||
radiobrowser.*
|
|
||||||
radiostation.*
|
|
||||||
bearplayer.*
|
|
||||||
mprisadaptor.*
|
|
||||||
bearwavecontroladaptor.*
|
|
||||||
qml/Main.qml
|
|
||||||
qml.qrc
|
|
||||||
```
|
|
||||||
|
|
||||||
## Runtime Requirements
|
- a local source build
|
||||||
|
- the included Arch `PKGBUILD`
|
||||||
- Linux desktop session (KDE Plasma recommended)
|
|
||||||
- Qt 6 runtime libraries
|
|
||||||
- Phonon4Qt6 + a Phonon backend (VLC backend recommended)
|
|
||||||
- Network access to Radio Browser instances
|
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
|
|
||||||
@@ -130,21 +161,7 @@ sudo apt install cmake ninja-build qt6-base-dev qt6-declarative-dev qt6-tools-de
|
|||||||
|
|
||||||
Note: exact package names can vary between distro releases, and non-Arch dependency sets should currently be treated as best-effort guidance rather than a guaranteed tested path.
|
Note: exact package names can vary between distro releases, and non-Arch dependency sets should currently be treated as best-effort guidance rather than a guaranteed tested path.
|
||||||
|
|
||||||
## Installation Status
|
## Build And Install
|
||||||
|
|
||||||
BearWave should currently be understood as:
|
|
||||||
|
|
||||||
- officially documented for source builds
|
|
||||||
- most naturally aligned with Arch Linux packaging
|
|
||||||
- likely portable to other Linux distributions with Qt 6 / KF6 / Phonon packages available
|
|
||||||
- not yet positioned as a broadly packaged consumer desktop app
|
|
||||||
|
|
||||||
If you want the least surprising path today, use either:
|
|
||||||
|
|
||||||
- a local source build
|
|
||||||
- the included Arch `PKGBUILD`
|
|
||||||
|
|
||||||
## Build
|
|
||||||
|
|
||||||
From the repository root:
|
From the repository root:
|
||||||
|
|
||||||
@@ -153,24 +170,7 @@ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
|
|||||||
cmake --build build -j"$(nproc)"
|
cmake --build build -j"$(nproc)"
|
||||||
```
|
```
|
||||||
|
|
||||||
If you want a clean rebuild:
|
Optional local install:
|
||||||
|
|
||||||
```bash
|
|
||||||
rm -rf build
|
|
||||||
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
|
|
||||||
cmake --build build -j"$(nproc)"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Arch Linux (PKGBUILD)
|
|
||||||
|
|
||||||
For a clean, system-wide installation on Arch Linux, use the included `PKGBUILD`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
makepkg -si
|
|
||||||
```
|
|
||||||
This will automatically resolve dependencies, compile BearWave, and install it via pacman (`bearwave-git`).
|
|
||||||
|
|
||||||
## Install (User-local)
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cmake --install build --prefix "$HOME/.local"
|
cmake --install build --prefix "$HOME/.local"
|
||||||
@@ -180,50 +180,57 @@ kbuildsycoca6
|
|||||||
|
|
||||||
This installs:
|
This installs:
|
||||||
|
|
||||||
- Binary: `~/.local/bin/bearwave`
|
- binary: `~/.local/bin/bearwave`
|
||||||
- Desktop file: `~/.local/share/applications/org.kde.bearwave.desktop`
|
- desktop file: `~/.local/share/applications/org.kde.bearwave.desktop`
|
||||||
- Icon: `~/.local/share/icons/hicolor/256x256/apps/org.kde.bearwave.png`
|
- icon: `~/.local/share/icons/hicolor/256x256/apps/org.kde.bearwave.png`
|
||||||
|
|
||||||
Note: the generated desktop file uses the install prefix chosen during `cmake --install`.
|
Note: the generated desktop file uses the install prefix chosen during `cmake --install`.
|
||||||
|
|
||||||
## Run
|
If you want a clean rebuild:
|
||||||
|
|
||||||
- From launcher/menu: search for **BearWave**
|
|
||||||
- Or terminal:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
~/.local/bin/bearwave
|
rm -rf build
|
||||||
|
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
|
||||||
|
cmake --build build -j"$(nproc)"
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage Guide
|
## Runtime Requirements
|
||||||
|
|
||||||
### Basic Flow
|
- Linux desktop session
|
||||||
|
- KDE Plasma recommended
|
||||||
|
- Qt 6 runtime libraries
|
||||||
|
- Phonon4Qt6 with a working backend
|
||||||
|
- network access to Radio Browser instances
|
||||||
|
|
||||||
1. Open a station page (Top/DE/NL/Favorites or quick filters)
|
## Usage
|
||||||
2. Pick a station and press play
|
|
||||||
3. Add favorites for quick access
|
|
||||||
4. Use Resume to continue from last session
|
|
||||||
|
|
||||||
### Keyboard Shortcuts
|
### Basic flow
|
||||||
|
|
||||||
- `Space`: Play/Pause
|
1. Open a station page such as Top, DE, NL, Favorites, or a quick filter.
|
||||||
- `Ctrl+F`: Focus search field
|
2. Select a station and start playback.
|
||||||
|
3. Add favorites for quick reuse.
|
||||||
|
4. Use Resume to continue from the last station and volume state.
|
||||||
|
|
||||||
|
### Keyboard shortcuts
|
||||||
|
|
||||||
|
- `Space`: play/pause
|
||||||
|
- `Ctrl+F`: focus search field
|
||||||
|
|
||||||
### Sorting
|
### Sorting
|
||||||
|
|
||||||
Use the sort controls to reorder station lists by:
|
Sort station lists by:
|
||||||
|
|
||||||
- Name (A-Z)
|
- name
|
||||||
- Bitrate
|
- bitrate
|
||||||
- Votes
|
- votes
|
||||||
|
|
||||||
## Data and Persistence
|
## Data And Persistence
|
||||||
|
|
||||||
BearWave stores user state under:
|
BearWave stores user state under:
|
||||||
|
|
||||||
- Favorites: `~/.config/bearwave/favorites.json`
|
- favorites: `~/.config/bearwave/favorites.json`
|
||||||
- Last station + volume: `~/.config/bearwave/state.json`
|
- last station + volume: `~/.config/bearwave/state.json`
|
||||||
- API Cache (RadioBrowser): `~/.cache/bearwave/api_cache/`
|
- API cache: `~/.cache/bearwave/api_cache/`
|
||||||
|
|
||||||
If these files are removed, app state resets to defaults or performs a fresh API sync.
|
If these files are removed, app state resets to defaults or performs a fresh API sync.
|
||||||
|
|
||||||
@@ -232,26 +239,10 @@ If these files are removed, app state resets to defaults or performs a fresh API
|
|||||||
BearWave exposes playback through MPRIS, so it works with:
|
BearWave exposes playback through MPRIS, so it works with:
|
||||||
|
|
||||||
- Plasma media applets/widgets
|
- Plasma media applets/widgets
|
||||||
- Global media key handling
|
- global media key handling
|
||||||
- External MPRIS-capable controllers
|
- external MPRIS-capable controllers
|
||||||
|
|
||||||
## Scope
|
## Autostart
|
||||||
|
|
||||||
BearWave is intentionally focused.
|
|
||||||
|
|
||||||
What it is:
|
|
||||||
|
|
||||||
- a KDE-oriented internet radio desktop app
|
|
||||||
- a lightweight browser/player for online radio streams
|
|
||||||
- a Plasma-friendly app with MPRIS and tray integration
|
|
||||||
|
|
||||||
What it is not:
|
|
||||||
|
|
||||||
- a local music library manager
|
|
||||||
- a general-purpose podcast client
|
|
||||||
- a cross-platform media suite targeting every desktop equally
|
|
||||||
|
|
||||||
## Autostart (Optional)
|
|
||||||
|
|
||||||
Enable autostart:
|
Enable autostart:
|
||||||
|
|
||||||
@@ -270,26 +261,33 @@ rm -f "$HOME/.config/autostart/org.kde.bearwave.desktop"
|
|||||||
|
|
||||||
### No audio playback
|
### No audio playback
|
||||||
|
|
||||||
- Ensure `phonon-qt6` and `phonon-qt6-vlc` (or equivalent) are installed
|
- ensure `phonon-qt6` and `phonon-qt6-vlc` or equivalent are installed
|
||||||
- Ensure `vlc` is installed
|
- ensure `vlc` is installed
|
||||||
- Test another station URL (some streams go offline)
|
- test another station URL because some streams go offline
|
||||||
|
|
||||||
### App icon/menu entry not updating
|
### App icon or launcher entry not updating
|
||||||
|
|
||||||
- Re-run:
|
Re-run:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
update-desktop-database "$HOME/.local/share/applications"
|
update-desktop-database "$HOME/.local/share/applications"
|
||||||
kbuildsycoca6
|
kbuildsycoca6
|
||||||
```
|
```
|
||||||
|
|
||||||
- Log out/in if desktop cache is stale
|
If desktop caches are stale, a logout/login cycle may still be required.
|
||||||
|
|
||||||
### Station list empty or slow
|
### Station list empty or slow
|
||||||
|
|
||||||
- Verify internet connectivity
|
- verify internet connectivity
|
||||||
- Radio Browser endpoint may be rate-limited temporarily
|
- Radio Browser may be temporarily rate-limited or degraded
|
||||||
- Try another station category/filter
|
- try another station category or filter
|
||||||
|
|
||||||
|
## Current Limitations
|
||||||
|
|
||||||
|
- UI language is currently primarily German
|
||||||
|
- packaging and install guidance are strongest on Arch Linux
|
||||||
|
- broader distro support is not yet validated to the same standard
|
||||||
|
- there are no official binary releases for non-technical end users yet
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
@@ -304,34 +302,16 @@ Before opening a larger change, it is worth checking whether it matches the proj
|
|||||||
|
|
||||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for local build and review expectations.
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for local build and review expectations.
|
||||||
|
|
||||||
## Release Notes
|
|
||||||
|
|
||||||
For an initial public repository, the recommended install paths are:
|
|
||||||
|
|
||||||
- build from source
|
|
||||||
- user-local install via CMake
|
|
||||||
- Arch Linux via the included `PKGBUILD`
|
|
||||||
|
|
||||||
If broader distribution is added later, Flatpak or AppImage would be reasonable follow-ups.
|
|
||||||
|
|
||||||
## Current Limitations
|
|
||||||
|
|
||||||
- UI language is currently primarily German
|
|
||||||
- packaging and install guidance are strongest on Arch Linux
|
|
||||||
- broader distro support is not yet validated to the same standard
|
|
||||||
- there are no official binary releases for non-technical end users yet
|
|
||||||
|
|
||||||
## Development Notes
|
## Development Notes
|
||||||
|
|
||||||
- Main UI: `src/qml/Main.qml`
|
- main UI: `src/qml/Main.qml`
|
||||||
- Backend orchestration: `src/radiobackend.cpp`
|
- backend orchestration: `src/radiobackend.cpp`
|
||||||
- Stream playback: `src/bearplayer.cpp`
|
- stream playback: `src/bearplayer.cpp`
|
||||||
- API layer: `src/radiobrowser.cpp`
|
- API layer: `src/radiobrowser.cpp`
|
||||||
- MPRIS adapter: `src/mprisadaptor.cpp`
|
- MPRIS adapter: `src/mprisadaptor.cpp`
|
||||||
|
|
||||||
For contributor/agent workflow and guardrails, see `AGENTS.md`.
|
For contributor and agent guardrails, see `AGENTS.md`.
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
This project is licensed under the MIT License.
|
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
|
||||||
See `LICENSE` for full text.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user