bearwave-mac/README.md

BearWave for macOS

Native macOS port of BearWave, focused on fast internet radio playback.

BearWave for macOS is a SwiftUI + AVFoundation desktop app built around the same product idea as the Linux version: quick station discovery, lightweight playback, favorites, recents, and native desktop integration without turning the app into a general-purpose audio suite.

Current release target: v0.1.0-alpha.1

Screenshots

Features

• Native macOS 26 app built with SwiftUI
• Radio Browser integration
• Top, Germany, Netherlands, World, and Search Results pages
• Favorites, recents, and manual stations
• Station folders for organizing saved stations
• Menu bar controls
• Mini Player with Cmd+M
• Explicit playback states:
  • connecting
  • buffering
  • playing
  • paused
  • stopped
  • failed
• Stream metadata support through AVPlayerItemMetadataOutput
• Station artwork/favicon caching
• Resume last station on launch
• English and German localization

Product Direction

This macOS version is intentionally radio-first.

That means:

• internet radio is the core product
• native macOS behavior is preferred over KDE/Qt parity
• podcast features are intentionally out of scope

License

This project follows the upstream BearWave licensing direction and is licensed under GPL-3.0-or-later.

See LICENSE.

Build

swift build --disable-index-store

Run the app bundle through the local staging script:

./script/build_and_run.sh

Useful script modes:

./script/build_and_run.sh --verify
./script/build_and_run.sh --debug
./script/build_and_run.sh --logs
./script/build_and_run.sh --telemetry

Run the lightweight checks:

CLANG_MODULE_CACHE_PATH=/private/tmp/bearwave-clang-cache swift run --disable-index-store BearWaveChecks

Project Layout

• Package.swift SwiftPM package definition
• Sources/BearWaveApp app entrypoint and scene wiring
• Sources/BearWaveCore shared app logic, models, stores, services, views, and resources
• Tests/BearWaveChecks lightweight verification executable
• script/build_and_run.sh local build, bundle, and launch script
• screens/ README screenshots

Persistence

BearWave stores data under native macOS locations:

• Application Support/BearWave/
  • favorites.json
  • manual-stations.json
  • groups.json
  • state.json
• Caches/BearWave/
  • api_cache/
  • artwork cache files

On first run it can also import older Linux-style BearWave files when present:

• ~/.config/bearwave/favorites.json
• ~/.config/bearwave/state.json

Current Status

Implemented and working:

• radio browsing and global search
• station playback
• playback status reporting
• metadata display
• favorites, recents, manual stations
• station folders
• menu bar controls
• mini player

Still pragmatic rather than release-ready:

• SwiftPM-staged .app bundle
• debug-oriented signing and packaging
• custom app-bundle staging script

This repository is currently in an early alpha state.

Roadmap

• improve release packaging, signing, and notarization
• expand playback diagnostics
• strengthen tests around playback state and search ranking
• refine cache management
• keep station folders lightweight and clearly radio-focused