# 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.

## Screenshots

![Main station browser](screens/screen1.png)

![Favorites and station folders](screens/screen2.png)

![Active playback state](screens/screen3.png)

## 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

## Build

```bash
swift build --disable-index-store
```

Run the app bundle through the local staging script:

```bash
./script/build_and_run.sh
```

Useful script 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
```

Run the lightweight checks:

```bash
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

## 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