buzzert
cedd0c6aa2
Show only configured players, enqueue and play immediately on row tap, and keep the URL on one truncated line. Remove extension discovery, selection state, and the bottom action while retaining progress and existing duplicate/partial-failure guards. Preserve main-app discovery. Update share-extension guidance to match the simplified flow.
105 lines
4.8 KiB
Markdown
105 lines
4.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
QueueCube is a SwiftUI-based jukebox client application for iOS and macOS (via Mac Catalyst). It provides a frontend for controlling a server-based jukebox system that supports playlist management, favorites, and playback controls.
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
- **API.swift**: Central networking layer that handles all communication with the jukebox server. Includes REST API methods for playback control, playlist management, and WebSocket events for real-time updates.
|
|
- **ContentView.swift**: Main view controller containing the `MainViewModel` that coordinates between UI components and API calls. Handles WebSocket event processing and data flow.
|
|
- **Server.swift**: Represents individual jukebox servers with support for both manual configuration and Bonjour service discovery.
|
|
- **ServerDiscovery.swift**: Main-app Bonjour browsing and bounded, cancellation-safe endpoint resolution for Add Server.
|
|
- **RequestBuilder.swift**: Shared extension-safe HTTP builder and error handling.
|
|
- **SharePlayback.swift**: Append once, select the new queue item, unpause, and verify playback using existing endpoints.
|
|
- **Settings.swift**: Manages multiple server configurations stored in UserDefaults with validation through `SettingsViewModel` that tests connectivity on URL changes.
|
|
|
|
### Data Flow
|
|
|
|
1. **Multiple Server Support**: Array of `Server` objects stored in UserDefaults with selected server tracking
|
|
2. **Settings**: Server configurations validated asynchronously via API calls with live connectivity testing
|
|
3. **Real-time Updates**: WebSocket connection provides live updates for playlist changes, playback state, and volume
|
|
4. **API Integration**: All server communication goes through the `API` struct using a fluent `RequestBuilder` pattern
|
|
5. **State Management**: Uses SwiftUI's `@Observable` pattern for reactive UI updates
|
|
|
|
### Request Builder Pattern
|
|
|
|
The API layer uses a fluent builder pattern for HTTP requests:
|
|
```swift
|
|
try await request()
|
|
.path("/nowplaying")
|
|
.json()
|
|
```
|
|
|
|
This provides type-safe, composable API calls with automatic error handling and connection state management.
|
|
|
|
### Key Features
|
|
|
|
- **Real-time sync**: WebSocket events automatically refresh UI when server state changes
|
|
- **Cross-platform**: Supports iOS, iPadOS, and macOS via Mac Catalyst
|
|
- **Settings validation**: Live server connectivity testing with visual feedback
|
|
- **Error handling**: Connection state management with user-friendly error displays
|
|
|
|
## Development Commands
|
|
|
|
### Building
|
|
```bash
|
|
# Build for iOS Simulator
|
|
xcodebuild -project QueueCube.xcodeproj -scheme QueueCube -destination 'platform=iOS Simulator,name=iPhone 15' build
|
|
|
|
# Build for Mac Catalyst
|
|
xcodebuild -project QueueCube.xcodeproj -scheme QueueCube -destination 'platform=macOS,variant=Mac Catalyst' build
|
|
```
|
|
|
|
### Running
|
|
- Open `QueueCube.xcodeproj` in Xcode
|
|
- Select target device (iOS Simulator or Mac)
|
|
- Run with Cmd+R
|
|
|
|
## API Endpoints Reference
|
|
|
|
The server API includes these endpoints:
|
|
- `GET /nowplaying` - Current playback status
|
|
- `GET /playlist` - Current playlist items
|
|
- `GET /favorites` - User favorites
|
|
- `POST /play`, `/pause`, `/skip`, `/previous` - Playback controls
|
|
- `POST /playlist` - Append media URL (append-play starts only when idle)
|
|
- `POST /skip/{index}` - Select and play a zero-based playlist index; existing queue remains
|
|
- `DELETE /playlist/{index}` - Remove playlist item
|
|
- `POST /volume` - Set volume level
|
|
- `WS /events` - WebSocket for real-time updates
|
|
|
|
## UI Structure
|
|
|
|
### View Hierarchy
|
|
```
|
|
QueueCubeApp
|
|
└── ContentView (coordination layer)
|
|
└── MainView (tab management)
|
|
├── PlaylistView (with embedded NowPlayingView)
|
|
├── FavoritesView (favorites management)
|
|
└── SettingsView (server configuration)
|
|
├── ServerListSettingsView
|
|
├── AddServerView
|
|
└── GeneralSettingsView
|
|
```
|
|
|
|
### Key Views
|
|
- **ContentView**: Main coordinator that manages API instances and global state
|
|
- **MainView**: Tab-based navigation container with platform-specific adaptations
|
|
- **PlaylistView**: Scrollable list of queued media with reorder/delete actions, includes embedded NowPlayingView
|
|
- **NowPlayingView**: Playback controls and current track display
|
|
- **AddMediaBarView**: Input field for adding new media URLs to playlist
|
|
- **SettingsView**: Multi-server configuration with live validation and service discovery
|
|
|
|
## Share extension
|
|
|
|
`QueueCubeShare` is embedded in iOS and Mac Catalyst builds. It reads an App Group
|
|
settings snapshot and reuses the API code. Tapping a saved player queues and plays
|
|
the shared link; discovery remains in the main app. See [SHARE_EXTENSION.md](SHARE_EXTENSION.md)
|
|
for authentication limitations, queue/play failure semantics, signing setup, and focused tests.
|