Create BearWave macOS radio-first app
This commit is contained in:
Sebastian Palencsar
120
README.md
Normal file
120
README.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# BearWave for macOS
|
||||
|
||||
Native macOS 26 port of the Linux/KDE app BearWave.
|
||||
|
||||
This repository is the current SwiftUI + AVFoundation version built as a
|
||||
SwiftPM app. The product scope is focused internet radio on macOS.
|
||||
|
||||
## Current Scope
|
||||
|
||||
- Radio Browser integration for Top, Germany, Netherlands, World, search, favorites, recents, and manual stations
|
||||
- Native SwiftUI macOS UI with sidebar, list, detail panel, player bar, settings, and menu bar extra
|
||||
- Station folders for organizing favorites and saved stations
|
||||
- Stream playback through `AVPlayer`
|
||||
- Playback states: connecting, buffering, playing, paused, stopped, failed
|
||||
- Stream metadata display via `AVPlayerItemMetadataOutput`
|
||||
- Station favicons/artwork with local disk cache
|
||||
- Now Playing artwork resolution with fallback chain: metadata lookup, station favicon, app default artwork
|
||||
- Mini Player with `Cmd+M`
|
||||
|
||||
## Project Layout
|
||||
|
||||
- `Package.swift`
|
||||
SwiftPM package with:
|
||||
- `BearWaveCore` shared app logic and resources
|
||||
- `BearWave` app executable
|
||||
- `BearWaveChecks` lightweight verification executable
|
||||
- `Sources/BearWaveApp`
|
||||
App entrypoint and scene setup
|
||||
- `Sources/BearWaveCore`
|
||||
App logic split into:
|
||||
- `App/` high-level app coordinator (`AppModel.swift`)
|
||||
- `Models/` domain models (`RadioStation`, `StationGroup`, `PlaybackStatus`, `PlaybackError`, `StationPage`)
|
||||
- `Services/` Radio Browser client, playback controller, artwork loading, Now Playing artwork resolution
|
||||
- `Stores/` persistence, settings, station library
|
||||
- `Views/` SwiftUI UI (sidebar, list, detail, player bar, settings, menu bar, mini player)
|
||||
- `Support/` resource helpers
|
||||
- `Resources/` localized strings, assets, entitlements placeholder
|
||||
- `Tests/BearWaveChecks`
|
||||
Executable smoke checks for decoding, search normalization, filtering, and library behavior
|
||||
- `script/build_and_run.sh`
|
||||
Local build, bundle, and launch entrypoint
|
||||
|
||||
## Build and Run
|
||||
|
||||
```bash
|
||||
./script/build_and_run.sh
|
||||
```
|
||||
|
||||
Useful modes:
|
||||
|
||||
```bash
|
||||
./script/build_and_run.sh --verify
|
||||
./script/build_and_run.sh --debug
|
||||
./script/build_and_run.sh --logs
|
||||
./script/build_and_run.sh --telemetry
|
||||
```
|
||||
|
||||
## Development Notes
|
||||
|
||||
- Target platform is `macOS 26`
|
||||
- Preferred workspace is:
|
||||
`/Users/sebastian/Development/radioappmac`
|
||||
- Build with:
|
||||
`swift build --disable-index-store`
|
||||
- Lightweight verification:
|
||||
`CLANG_MODULE_CACHE_PATH=/private/tmp/bearwave-clang-cache swift run --disable-index-store BearWaveChecks`
|
||||
- The generated app bundle lives in:
|
||||
`./dist/BearWave.app`
|
||||
- The run script stages SwiftPM resource bundles and localization directories manually into the app bundle
|
||||
|
||||
## Playback and Metadata Notes
|
||||
|
||||
- Audio playback uses `AVPlayer`
|
||||
- Stream metadata is read through `AVPlayerItemMetadataOutput`
|
||||
- `PlaybackController` exposes explicit playback states instead of a simple play/pause boolean
|
||||
- Some radio streams provide current-song metadata; many do not
|
||||
- `MediaPlayer` is imported with `@preconcurrency` because the app updates `MPNowPlayingInfoCenter`
|
||||
- `MPMediaItemArtwork` is created from a stable `CGImage` request handler
|
||||
- ATS is explicitly opened for media and `http://` streams in the generated app `Info.plist`, otherwise many radio streams do not play
|
||||
|
||||
## Persistence
|
||||
|
||||
Data is stored under native macOS locations:
|
||||
|
||||
- `Application Support/BearWave/`
|
||||
- `favorites.json`
|
||||
- `manual-stations.json`
|
||||
- `groups.json`
|
||||
- `state.json`
|
||||
|
||||
- `Caches/BearWave/`
|
||||
- `api_cache/`
|
||||
- artwork cache files
|
||||
|
||||
The app also tries to import old Linux-style files on first run if present:
|
||||
|
||||
- `~/.config/bearwave/favorites.json`
|
||||
- `~/.config/bearwave/state.json`
|
||||
|
||||
## Current UX Behavior
|
||||
|
||||
- Search is global against Radio Browser and independent from the current browse page
|
||||
- Search results appear on a dedicated `Search Results` page
|
||||
- Search ranking intentionally filters naive mid-word matches such as `slam` matching `Islamabad`
|
||||
- A right-side detail panel shows station metadata and current stream metadata when available
|
||||
- German localization is active across the app
|
||||
|
||||
## Known Technical Edges
|
||||
|
||||
- The app is currently a SwiftPM-staged `.app`, not an Xcode-managed release app
|
||||
- Debug signing and sandbox behavior are intentionally pragmatic, not release-ready
|
||||
- Resource handling is functional but still tied to the custom staging script
|
||||
|
||||
## Suggested Next Work
|
||||
|
||||
- Improve packaging, signing, and notarization
|
||||
- Add more targeted playback diagnostics per stream failure mode
|
||||
- Expand tests around playback-state transitions and search ranking
|
||||
- Add cache eviction for memory and disk caches
|
||||
- Keep station folders lightweight and radio-focused
|
||||
Reference in New Issue
Block a user