121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# 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
|