Files

T

buzzert cedd0c6aa2 ios: simplify share extension to saved-player tap-to-play

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.

2026-10-21 01:06:45 -07:00

4.8 KiB

Raw Permalink Blame History

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

Multiple Server Support: Array of Server objects stored in UserDefaults with selected server tracking
Settings: Server configurations validated asynchronously via API calls with live connectivity testing
Real-time Updates: WebSocket connection provides live updates for playlist changes, playback state, and volume
API Integration: All server communication goes through the API struct using a fluent RequestBuilder pattern
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:

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

# 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

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 for authentication limitations, queue/play failure semantics, signing setup, and focused tests.

4.8 KiB Raw Permalink Blame History