Website Content
diff --git a/notes/AnimatedArtworkImplementation.md b/notes/AnimatedArtworkImplementation.md
new file mode 100644
index 0000000..b627392
--- /dev/null
+++ b/notes/AnimatedArtworkImplementation.md
@@ -0,0 +1,132 @@
+# Animated Lock-Screen Artwork (iOS 26)
+
+Implementation guide for bringing animated “Now Playing” artwork to Blankie presets in iOS 26, with graceful fallbacks for earlier OS versions and motion-sensitive contexts.
+
+## Scope & Objectives
+
+- Surface a short looping animation for the active preset on Lock Screen, Control Center, Now Playing widgets, and other system surfaces that honour `MPNowPlayingInfoProperty1x1AnimatedArtwork`.
+- Keep static artwork behaviour unchanged everywhere else; animated keys are additive.
+- Ensure users can opt into bundled loops or import their own video per preset.
+- Respect Reduced Motion, Low Power Mode, and an explicit app-level toggle.
+
+## Compatibility Matrix
+
+- **Animated path**: iOS 26+ devices that report support for `MPNowPlayingInfoProperty1x1AnimatedArtwork`, Reduce Motion OFF, Low Power Mode OFF, and the user setting enabled.
+- **Static fallback**: iOS 15–25, CarPlay surfaces that do not opt in, Reduce Motion ON, Low Power Mode ON, or when animated assets are missing/corrupt.
+- Always publish the static `MPMediaItemPropertyArtwork` entry to guarantee a baseline image on every surface.
+
+## Data Model & Storage
+
+- Add `AnimatedArtworkRef` and `staticArtworkPath` to `Preset` in `Blankie/Models/Preset.swift`.
+
+ ```swift
+ struct AnimatedArtworkRef: Codable, Hashable {
+ enum Source: String, Codable { case auto, bundled, custom }
+ var source: Source
+ var loopPath: String? // Documents-relative path (e.g. "Artwork/
.mov")
+ var previewPath: String? // Documents-relative path (e.g. "Artwork/.jpg")
+ var preferredAspect: String? // "1x1" today; keep string for future 16x9/9x16 keys
+ }
+ ```
+
+- Store built-in and user imports under `Documents/Artwork/…`. Keep file naming deterministic (`.mov/.jpg`) to avoid collisions and simplify export/import.
+- Increment the preset schema version (e.g., to `2`) and add a migration that initialises `artwork = nil` and `staticArtworkPath` from legacy data if present.
+- Update preset serialisation, export/import flows, and sample JSON seeds to carry the new fields.
+
+## Bundled Assets
+
+- Place two demo loops and their JPG previews in `Blankie/Assets/AnimatedArtwork/`.
+ - Suggested names: `RainLoop.mov`, `RainLoop.jpg`, `CampfireLoop.mov`, `CampfireLoop.jpg`.
+ - Encode as HEVC or H.264, 1080×1080, 3–7 s, muted, < 12 MB.
+- Expose them via an enum or lookup table in code so the picker can copy the correct file into the Documents sandbox on selection.
+- Ensure the asset catalog or build phase copies the `.mov` and `.jpg` files into the main bundle for runtime access.
+
+## Animated Artwork Publisher
+
+- Add `Blankie/Shared/NowPlaying/BlankieAnimatedArtwork.swift` implementing `@MainActor func publishNowPlaying(for preset: Preset)`.
+- Behavioural flow:
+ 1. Start with existing `nowPlayingInfo` and set `MPMediaItemPropertyTitle`/`Artist`.
+ 2. If `preset.staticArtworkPath` exists and loads, set `MPMediaItemPropertyArtwork` using `MPMediaItemArtwork`.
+ 3. Gate animated artwork behind:
+ - `#available(iOS 26, *)`
+ - `UIAccessibility.isReduceMotionEnabled == false`
+ - `ProcessInfo.processInfo.isLowPowerModeEnabled == false`
+ - App-level “Lock-Screen Background” toggle (new setting).
+ - Non-nil `AnimatedArtworkRef.loopPath` and `previewPath` that can be loaded.
+ 4. Query `MPNowPlayingInfoCenter.supportedAnimatedArtworkKeys`; proceed only if it contains `MPNowPlayingInfoProperty1x1AnimatedArtwork`.
+ 5. Build `AVURLAsset` for the loop video and `UIImage` preview, then assign an `MPMediaItemAnimatedArtwork` instance into the `nowPlayingInfo` dictionary under the animated key.
+ 6. Assign the final dictionary back to `MPNowPlayingInfoCenter.default().nowPlayingInfo`.
+- Provide a helper `func appDocumentsPath(_ relative: String) -> URL` to keep path handling consistent across the app.
+
+## Playback Integration Points
+
+- Invoke `publishNowPlaying(for:)` whenever playback starts or resumes, the active preset changes (e.g., QuickMix, next/previous), artwork metadata is updated, or the user toggles Lock-Screen background in Settings.
+- Centralise these calls in the playback manager/view model to avoid race conditions between UI components.
+- Consider debouncing rapid preset switches to avoid thrashing the Now Playing center.
+
+## Preset Editor UI
+
+- Create `Blankie/Features/Presets/AnimatedArtworkPicker.swift` (SwiftUI):
+ - Segmented control for `Auto (scene)`, `Built-in loop`, `Custom video…`.
+ - When switching sources, initialise `AnimatedArtworkRef` if needed and update `source`.
+ - For built-in selection, copy the chosen bundle asset into Documents/Artwork and update `loopPath` + `previewPath`.
+ - For custom video:
+ 1. Use `PhotosPicker` (`matching: .videos`) to select a clip.
+ 2. Copy to Documents/Artwork/`.mov`.
+ 3. Generate a preview JPG using `AVAssetImageGenerator` frame 0 → Documents/Artwork/`.jpg`.
+ 4. Update the bound `AnimatedArtworkRef`.
+ 5. Optionally, warn if duration > 7 s or file size > 15 MB (future enhancement).
+- Surface a thumbnail/loop preview in the editor (static preview image is sufficient for v1).
+
+## Settings Toggle
+
+- Add “Lock-Screen Background” (default ON) to Settings.
+- Store in persistent settings (UserDefaults or existing config store).
+- Ensure toggling republishers Now Playing info and updates the UI state.
+
+## Reduce Motion & Low Power
+
+- Listen for `UIAccessibility.reduceMotionStatusDidChangeNotification` and `NSProcessInfoPowerStateDidChange` to re-publish metadata if system preferences change mid-session.
+- Provide local logging when animated artwork is skipped, aiding QA.
+
+## Migration & Backups
+
+- Include animated artwork files in existing preset export/import flows.
+- Update backup/restore scripts to include `Documents/Artwork/`.
+- When deleting a preset or removing custom artwork, delete orphaned files to keep storage tidy.
+
+## QA Matrix
+
+- Devices: iOS 26 simulator + physical device (animated path), one iOS 15–25 device (static path), at least one CarPlay session if possible.
+- Scenarios:
+ 1. Start playback → animated loop shows on Lock Screen and Control Center within 1 s.
+ 2. Switch presets rapidly → animation updates without stale imagery.
+ 3. Reduce Motion ON → static image only; turning OFF re-enables animation after republish.
+ 4. Low Power Mode ON while playing → animation removed on next publish.
+ 5. Background/foreground transitions keep the chosen artwork.
+ 6. Route changes (Bluetooth, AirPlay, calls) do not clear animated keys.
+ 7. Import oversized clip → handled gracefully (warning or truncation if implemented).
+ 8. CarPlay → static artwork present, no crashes.
+
+## Optional Analytics
+
+- Events: `animated_artwork_enabled`, `animated_artwork_disabled`, `animated_artwork_imported`.
+- Properties: preset ID, loop source (`auto/bundled/custom`), file size buckets, duration buckets.
+- Guard analytics emissions behind privacy consent.
+
+## Definition of Done
+
+- Preset model schema migrated and persisted across app surfaces.
+- Publisher sets all static fields and only appends `MPNowPlayingInfoProperty1x1AnimatedArtwork` when supported.
+- Preset editor exposes auto/bundled/custom flows; imports create preview JPGs.
+- Bundled loops compile into the app and appear in picker.
+- Settings toggle works and re-publishes metadata immediately.
+- Reduce Motion & Low Power overrides verified.
+- QA scenarios above pass on target OS versions.
+- Release notes include: “Animated Lock-Screen backgrounds for presets (iOS 26+). Choose built-in loops or attach your own short video. Respects Reduced Motion and Low Power Mode.”
+
+## Open Questions / Follow-ups
+
+- Do we need trimming/compression UI for custom videos on day one, or is a warning modal sufficient?
+- Should auto mode derive artwork from scene metadata or fallback to static imagery today?
+- Coordinate with marketing for loop asset approvals before shipping.
diff --git a/notes/CARPLAY.md b/notes/CARPLAY.md
new file mode 100644
index 0000000..e9e8f25
--- /dev/null
+++ b/notes/CARPLAY.md
@@ -0,0 +1,55 @@
+# CarPlay Implementation
+
+## Overview
+
+Blankie has a working CarPlay prototype that provides simplified interface to access presets. Building the app with CarPlay to run outside of a simulator, even on your own devices, requires an Apple-approved entitlement granted per developer bundle ID, so the Blankie Xcode project has separate build schemes to support both standard builds (that any contributor can build) and CarPlay-enabled builds (that Blankie's maintainers can use in the future when Blankie's entitlement is approved to build official releases).
+
+## Scheme Details
+
+| Component | Universal | iOS with CarPlay |
+|-----------|---------------|---------------|
+| **Build Configs** | `Debug`, `Release` | `Debug-CarPlay`, `Release-CarPlay` |
+| **Supported Platforms** | All (iOS, macOS, visionOS) | iPhone only |
+| **Entitlements** | `Blankie.entitlements` | `Blankie-CarPlay.entitlements` |
+| **Info.plist** | `Blankie-Info.plist` | `Blankie-CarPlay.plist` |
+| **Scene Generation** | Automatic (`YES`) | Manual (`NO`) |
+| **Compiler Flag** | — | `CARPLAY_ENABLED` |
+
+The iOS with CarPlay configuration:
+
+- **Will only allow iOS builds** (CarPlay is not supported on iPad, Mac, or visionOS)
+- Uses separate entitlements that include `com.apple.developer.carplay-audio`
+- Defines a custom Info.plist with CarPlay scene configuration
+- Sets `UIApplicationSceneManifest_Generation` to `NO` for manual scene control
+- Defines `CARPLAY_ENABLED` for conditional compilation
+
+## Implementation Files
+
+- **`Blankie-CarPlay.entitlements`** — Adds the CarPlay audio entitlement
+- **`Blankie-CarPlay.plist`** — Defines the CarPlay scene configuration
+- **`CarPlaySceneDelegate.swift`** — Handles CarPlay scene lifecycle
+- **`UI/CarPlayInterface.swift`** — Main CarPlay user interface
+- **`UI/CarPlayStatusView.swift`** — CarPlay audio status display
+
+## Development Workflow
+
+To test or build a **non-CarPlay** version of the app for any platform, simply use the default **"Blankie (Universal)"** scheme. Any CarPlay code will be ignored and no special setup is required.
+
+To *test a **CarPlay** version of the app in a simulator*, you can use the **"Blankie (iOS with CarPlay)"** scheme without needing an Apple-approved entitlement. The iOS Simulator includes a CarPlay simulator (via I/O → External Displays → CarPlay).
+
+To **build a CarPlay version of the app for a *non-simulator destination*** you will need to use the **"Blankie (iOS with CarPlay)"** scheme, and you must have an Apple-approved entitlement for your developer bundle ID.
+
+### Conditional Compilation
+
+CarPlay-specific code can be wrapped in compiler directives to ensure it's only included in `Blankie (iOS with CarPlay)` builds:
+
+```swift
+#if CARPLAY_ENABLED
+// CarPlay-specific implementation
+import CarPlay
+
+extension AppDelegate: CPTemplateApplicationSceneDelegate {
+ // CarPlay scene delegate methods
+}
+#endif
+```
diff --git a/notes/CarPlayNotes.md b/notes/CarPlayNotes.md
new file mode 100644
index 0000000..56ca2d0
--- /dev/null
+++ b/notes/CarPlayNotes.md
@@ -0,0 +1,1159 @@
+# CarPlay Documentation Notes for Blankie
+
+This document contains notes from reviewing CarPlay documentation for potential features and implementation details relevant to Blankie, an ambient sound mixer app.
+
+---
+
+## 1. carplay/README.md
+
+**Key Points:**
+
+- CarPlay requires entitlements (need to request from Apple)
+- Supports iOS 12.0+ (Blankie targets iOS 16+ so we're good)
+- Music app integration guide available - directly relevant to Blankie
+- Templates available for audio apps:
+ - CPNowPlayingTemplate - for playback controls
+ - CPListTemplate - for listing presets/sounds
+ - CPGridTemplate - for grid of preset shortcuts
+ - CPTabBarTemplate - for organizing different sections
+- Alert templates (CPAlertTemplate, CPActionSheetTemplate) for user notifications
+
+**Relevant for Blankie:**
+
+- Focus on audio templates and music app integration guide
+- Tab bar structure could organize: Presets | Sounds | Now Playing
+- List template perfect for showing saved presets
+- Grid template could show favorite/recent presets
+
+---
+
+## 2. carplay/api-reference/other/overview.md
+
+**Key Points:**
+
+- CarPlay framework overview showing main categories
+- Requires iOS 12.0+ (Blankie is iOS 16+ so compatible)
+- Can integrate with SiriKit, CallKit, and MapKit
+- Audio section (lines 96-108) specifically for apps with audio entitlement
+- CPNowPlayingTemplate is a shared system template for Now Playing info
+- Templates provide consistent layout/appearance, framework controls UI aspects
+
+**Relevant for Blankie:**
+
+- Must have audio entitlement to access audio templates
+- CPNowPlayingTemplate is the main audio template
+- Can use general purpose templates: CPListTemplate, CPGridTemplate, CPTabBarTemplate
+- Framework handles touch target size, font size/color - good for consistency
+- Music app integration guide available (line 101)
+
+**Not Relevant:**
+
+- Navigation templates (need navigation entitlement)
+- Communication templates (need communication entitlement)
+- Parking/EV charging/food ordering templates
+- Sports mode features (for live sports streaming)
+
+---
+
+## 3. carplay/api-reference/other/index.md
+
+**Key Points:**
+
+- Same content as overview.md - appears to be a duplicate
+- Main index/overview page for CarPlay framework documentation
+
+**Notes:**
+
+- Skip detailed notes since this is identical to file #2
+
+---
+
+## 4. guides/getting-started/requesting-carplay-entitlements.md
+
+**Key Points:**
+
+- Must request entitlements via CarPlay Contact Us form at Apple
+- Need to agree to CarPlay Entitlement Addendum
+- Apple reviews requests using predefined criteria
+- Subject to additional App Store Review guidelines
+- Entitlement for audio apps: `com.apple.developer.carplay-audio`
+
+**Required Steps:**
+
+1. Request entitlement from Apple
+2. Add CarPlay capability to App ID in developer portal
+3. Create new provisioning profile
+4. Configure Xcode to use manual signing with new profile
+5. Add Entitlements.plist file with `com.apple.developer.carplay-audio` = true
+6. Set Code Signing Entitlements build setting to point to file
+
+**Testing:**
+
+- Use Xcode Simulator with I/O > External Displays > CarPlay
+- App should appear on CarPlay Home screen
+
+**Relevant for Blankie:**
+
+- Need to request audio entitlement specifically
+- Will need to disable automatic signing in Xcode
+- Must add Entitlements.plist (separate from existing .entitlements file)
+
+---
+
+## 5. guides/getting-started/displaying-content-in-carplay.md
+
+**Key Points:**
+
+- CarPlay uses scenes to manage UI (introduced in iOS 13)
+- Must add scene configuration to Info.plist
+- Scene delegate conforms to CPTemplateApplicationSceneDelegate
+- Non-navigation apps only use interface controller (no window access)
+- Navigation apps get window access for drawing map content
+
+**Info.plist Configuration:**
+
+```xml
+UIApplicationSceneManifest
+
+ UIApplicationSupportsMultipleScenes
+
+ UISceneConfigurations
+
+ CPTemplateApplicationSceneSessionRoleApplication
+
+
+ UISceneClassName
+ CPTemplateApplicationScene
+ UISceneDelegateClassName
+ MyCarPlaySceneDelegate
+
+
+
+
+```
+
+**Scene Delegate Implementation:**
+
+- Implement `templateApplicationScene(_:didConnect:)` method
+- Store reference to interface controller
+- Set root template (e.g., CPListTemplate, CPTabBarTemplate)
+- Use interface controller to push/pop templates
+
+**Relevant for Blankie:**
+
+- Audio apps don't get window access (only navigation apps do)
+- Must use scene-based approach (not AppDelegate)
+- Interface controller manages all UI through templates
+- Set root template on connection (likely CPTabBarTemplate)
+
+**Not Relevant:**
+
+- Dashboard scene (navigation apps only)
+- Window access and map rendering
+
+---
+
+## 6. guides/getting-started/using-the-carplay-simulator.md
+
+**Key Points:**
+
+- Access CarPlay simulator via I/O > External Displays > CarPlay
+- Default size: 800x480 pixels at @2x scale
+- Navigation apps can enable extra options for different screen sizes
+- Must have entitlements configured for app to appear
+
+**Testing Limitations in Simulator:**
+
+- Can't test locked iPhone state (apps must work when locked)
+- Can't test Siri integration
+- Can't test audio behavior (ducking, session management)
+
+**Recommended Testing:**
+
+- Use physical CarPlay system when possible
+- Wireless CarPlay allows Xcode debugging
+- Test multiple screen configurations (navigation apps)
+
+**Relevant for Blankie:**
+
+- Audio session management critical (must deactivate when not playing)
+- Must work when iPhone is locked
+- Standard 800x480 @2x window sufficient for audio apps
+- Consider Siri integration testing in real environment
+
+---
+
+## 7. guides/getting-started/supporting-previous-versions-of-ios.md
+
+**Key Points:**
+
+- iOS 14+ introduced CarPlay framework templates for audio apps
+- Before iOS 14, audio apps used Media Player framework
+- Can support both old and new approaches simultaneously
+
+**Audio App Entitlements:**
+
+- iOS 14+: `com.apple.developer.carplay-audio` (CarPlay framework)
+- iOS 13 and earlier: `com.apple.developer.playable-content` (Media Player framework)
+- For backward compatibility, include both entitlements:
+
+```xml
+com.apple.developer.playable-content
+
+com.apple.developer.carplay-audio
+
+```
+
+**Relevant for Blankie:**
+
+- Since Blankie targets iOS 16+, we only need the new entitlement
+- No need for Media Player framework compatibility
+- Can use CarPlay framework templates exclusively
+- Simpler implementation without legacy support
+
+**Not Relevant:**
+
+- Communication app compatibility (different entitlements)
+- VoIP/CallKit integration
+
+---
+
+## 8. guides/integration/integrating-carplay-with-your-music-app.md
+
+**Key Points:**
+
+- Sample code demonstrates CPNowPlayingTemplate and CPListTemplate usage
+- Uses CPTabBarTemplate as root with multiple tabs
+- Integrates with MPMusicPlayerController for playback
+- Shows how to implement Siri App Selection
+
+**Code Structure Example:**
+
+- Root: CPTabBarTemplate with tabs (Playlists, Genres, Settings)
+- Each tab uses CPListTemplate with CPListItems
+- List items have handlers for playback actions
+- iOS 15+ adds assistant cell for Siri integration
+
+**Key Implementation Details:**
+
+```swift
+// Set root template
+interfaceController.setRootTemplate(CPTabBarTemplate(templates: tabTemplates))
+
+// List item with handler
+let listItem = CPListItem(text: playlist.name, detailText: "")
+listItem.handler = { item, completion in
+ // Start playback
+ completion()
+}
+
+// Assistant cell for Siri (iOS 15+)
+let configuration = CPAssistantCellConfiguration(
+ position: .top,
+ visibility: .always,
+ assistantAction: .playMedia)
+```
+
+**Music Player Integration:**
+
+- Subscribe to MPMusicPlayerController notifications
+- Listen for playback state changes
+- Listen for now playing item changes
+- Update UI based on player state
+
+**Siri App Selection:**
+
+- Use INMediaUserContext to declare eligibility
+- Set numberOfLibraryItems
+- Set subscriptionStatus
+- Call becomeCurrent()
+
+**Relevant for Blankie:**
+
+- Use CPTabBarTemplate for organizing presets/sounds/settings
+- Implement list item handlers for sound/preset selection
+- Integrate with existing AudioManager instead of MPMusicPlayerController
+- Consider assistant cell for voice control
+- Adapt notification pattern for AudioManager state changes
+
+---
+
+## 9. api-reference/templates/audio/cpnowplayingtemplate.md
+
+**Key Points:**
+
+- Shared system template - use CPNowPlayingTemplate.shared (don't instantiate)
+- Only available with audio entitlement
+- Displays info from MPNowPlayingInfoCenter and MPNowPlayingSession
+- Push onto navigation stack (can't present modally)
+- Customizable playback control buttons
+
+**Button Types Available:**
+
+- CPNowPlayingImageButton - custom image buttons
+- CPNowPlayingAddToLibraryButton - add to collection
+- CPNowPlayingMoreButton - more options
+- CPNowPlayingPlaybackRateButton - playback speed
+- CPNowPlayingRepeatButton - repeat modes
+- CPNowPlayingShuffleButton - shuffle modes
+
+**Key Properties:**
+
+- nowPlayingButtons - array of playback control buttons
+- isAlbumArtistButtonEnabled - make album/artist tappable
+- isUpNextButtonEnabled - show Up Next button
+- upNextTitle - customize Up Next button title
+
+**Observer Pattern:**
+
+- Must implement CPNowPlayingTemplateObserver for button interactions
+- Add observer with add(_:) method
+- Handles Album/Artist and Up Next button taps
+
+**Usage Example:**
+
+```swift
+// Get shared instance
+let nowPlayingTemplate = CPNowPlayingTemplate.shared
+
+// Configure buttons
+nowPlayingTemplate.nowPlayingButtons = [playButton, pauseButton, ...]
+
+// Add observer for interactions
+nowPlayingTemplate.add(self)
+
+// Push onto stack
+interfaceController.pushTemplate(nowPlayingTemplate, animated: true)
+```
+
+**Relevant for Blankie:**
+
+- Use for playback controls when sounds are playing
+- Integrate with AudioManager for play/pause/stop
+- Update MPNowPlayingInfoCenter with current preset/sounds
+- Consider custom buttons for sound control
+- Enable album/artist button for preset details
+
+---
+
+## 10. api-reference/templates/general/cptabbartemplate.md
+
+**Key Points:**
+
+- Container template that displays other templates as tabs
+- Use maximumTabCount to check tab limit at runtime
+- Must be set as root template (can't push or present modally)
+- Each tab has its own navigation hierarchy
+- Templates in tabs are treated as root templates
+
+**Creating Tab Bar:**
+
+```swift
+let tabBarTemplate = CPTabBarTemplate(templates: [template1, template2, template3])
+interfaceController.setRootTemplate(tabBarTemplate, animated: true)
+```
+
+**Managing Templates:**
+
+- Use transactional approach for updates
+- Get current templates, modify array, call updateTemplates(_:)
+- Can update tab titles with tabTitle property
+- Show badges with showsTabBadge = true
+
+**Delegate Pattern:**
+
+- Implement CPTabBarTemplateDelegate
+- Handles tab selection events
+- tabBarTemplate(_:didSelect:) called when user selects tab
+
+**Key Properties/Methods:**
+
+- templates - current array of templates
+- updateTemplates(_:) - update tabs
+- selectedTemplate - currently selected tab
+- select(_:) or selectTemplate(at:) - programmatically select tab
+- maximumTabCount - runtime tab limit
+
+**Relevant for Blankie:**
+
+- Perfect for organizing main sections
+- Suggested tabs: Presets | Sounds | Now Playing
+- Each tab can have CPListTemplate or other templates
+- Update tab badges for active sounds
+- Handle tab selection to update UI state
+
+---
+
+## 11. api-reference/templates/general/cplisttemplate.md
+
+**Key Points:**
+
+- Displays list of items grouped in sections
+- Available since iOS 12.0 (older than other templates)
+- Maximum limits checked at runtime: maximumSectionCount, maximumItemCount
+- Supports hierarchical navigation (up to 5 levels for audio apps)
+- Three types of list items: CPListItem, CPListImageRowItem, CPMessageListItem
+
+**Creating Lists:**
+
+```swift
+let sections = [CPListSection(items: listItems)]
+let listTemplate = CPListTemplate(title: "Presets", sections: sections)
+```
+
+**Assistant Cell (Siri Integration):**
+
+- Available for audio apps with INPlayMediaIntent support
+- Configure with CPAssistantCellConfiguration
+- Position at top, visibility always/whenLimited
+- assistantAction: .playMedia for audio apps
+
+**List Items:**
+
+- CPListItem - standard selectable item with text/detail/image
+- Each item has handler closure for selection
+- Can show playing indicator, accessory type, etc.
+
+**Managing Empty State:**
+
+- emptyViewTitleVariants - array of titles for empty list
+- emptyViewSubtitleVariants - array of subtitles
+- showsSpinnerWhileEmpty - show loading indicator
+
+**Key Methods:**
+
+- updateSections(_:) - transactional updates
+- indexPath(for:) - find item location
+- Delegate deprecated - use item handlers instead
+
+**Relevant for Blankie:**
+
+- Perfect for preset lists and sound categories
+- Use sections to group sounds by type
+- Implement handlers for preset/sound selection
+- Add assistant cell for "Play rain sounds" voice commands
+- Show playing indicator on active presets
+- Empty state for "No presets saved"
+
+---
+
+## 12. api-reference/templates/general/cpgridtemplate.md
+
+**Key Points:**
+
+- Displays grid of button items
+- Maximum 8 buttons (only first 8 shown if more provided)
+- More than 4 buttons automatically balances into 2 rows
+- Each button has title, image, and optional handler
+- Available since iOS 12.0
+
+**Creating Grid:**
+
+```swift
+let gridButtons = [
+ CPGridButton(titleVariants: ["Rain"], image: rainImage) { button in
+ // Handle tap
+ }
+]
+let gridTemplate = CPGridTemplate(title: "Quick Presets", gridButtons: gridButtons)
+```
+
+**Grid Button Properties:**
+
+- titleVariants - array of title strings
+- image - button icon
+- handler - tap action closure
+
+**Key Methods:**
+
+- updateGridButtons(_:) - update buttons
+- updateTitle(_:) - change title
+
+**Relevant for Blankie:**
+
+- Perfect for "Favorite Presets" quick access
+- Could show 8 most-used presets as grid
+- Each button loads and plays preset
+- Visual grid better than list for quick selection
+- Consider as alternative tab to preset list
+
+---
+
+## 13. api-reference/templates/alerts/cpalerttemplate.md
+
+**Key Points:**
+
+- Modal alert template for important messages
+- Must present modally with presentTemplate()
+- User dismisses via button or dismiss programmatically
+- Maximum action count determined at runtime
+- Available since iOS 12.0
+
+**Creating Alerts:**
+
+```swift
+let alertTemplate = CPAlertTemplate(
+ titleVariants: ["Error", "Something went wrong"],
+ actions: [
+ CPAlertAction(title: "OK", style: .default) { _ in
+ // Handle OK
+ },
+ CPAlertAction(title: "Cancel", style: .cancel) { _ in
+ // Handle cancel
+ }
+ ]
+)
+interfaceController.presentTemplate(alertTemplate, animated: true)
+```
+
+**Properties:**
+
+- titleVariants - array of title strings
+- actions - array of CPAlertAction objects
+
+**CPAlertAction Styles:**
+
+- .default - standard action
+- .cancel - cancel action
+- .destructive - destructive action (red)
+
+**Relevant for Blankie:**
+
+- Use for errors (e.g., "Failed to load preset")
+- Confirm destructive actions (e.g., "Delete all presets?")
+- System notifications (e.g., "Audio session interrupted")
+- Keep alerts minimal for driving safety
+
+---
+
+## 14. api-reference/other/cptemplateapplicationscenedelegate.md
+
+**Key Points:**
+
+- Protocol for handling CarPlay scene lifecycle
+- Inherits from UISceneDelegate
+- Must be specified in Info.plist configuration
+- Handles connection/disconnection of CarPlay
+- Available since iOS 13.0
+
+**Main Methods:**
+
+```swift
+// Non-navigation apps (audio apps use this)
+func templateApplicationScene(_ scene: CPTemplateApplicationScene,
+ didConnect controller: CPInterfaceController) {
+ // Store interface controller
+ // Set root template
+}
+
+// Navigation apps only (get window access)
+func templateApplicationScene(_ scene: CPTemplateApplicationScene,
+ didConnect controller: CPInterfaceController,
+ to window: CPWindow) {
+ // Additional window parameter for map drawing
+}
+
+// Disconnection
+func templateApplicationScene(_ scene: CPTemplateApplicationScene,
+ didDisconnectInterfaceController controller: CPInterfaceController) {
+ // Clean up
+}
+```
+
+**Additional Methods:**
+
+- contentStyleDidChange(_:) - handle light/dark mode changes
+- Methods for navigation alerts (navigation apps only)
+
+**Implementation for Blankie:**
+
+```swift
+class CarPlaySceneDelegate: NSObject, CPTemplateApplicationSceneDelegate {
+ var interfaceController: CPInterfaceController?
+
+ func templateApplicationScene(_ scene: CPTemplateApplicationScene,
+ didConnect controller: CPInterfaceController) {
+ self.interfaceController = controller
+
+ // Create root tab bar template
+ let tabBar = CPTabBarTemplate(templates: [presetsTemplate, soundsTemplate])
+ controller.setRootTemplate(tabBar, animated: false)
+ }
+}
+```
+
+**Relevant for Blankie:**
+
+- Use first didConnect method (audio apps don't get window)
+- Store interface controller reference for template management
+- Set up root template structure on connection
+- Handle cleanup on disconnection
+- Consider dark mode support
+
+---
+
+## Summary and Implementation Plan for Blankie CarPlay
+
+Based on the documentation review, here's the recommended implementation approach for Blankie's CarPlay interface:
+
+### Architecture Overview
+
+**1. Template Structure:**
+
+```txt
+CPTabBarTemplate (Root)
+├── Tab 1: "Presets" (CPListTemplate)
+│ ├── Assistant Cell (Siri integration)
+│ └── List of saved presets with play handlers
+├── Tab 2: "Sounds" (CPListTemplate or CPGridTemplate)
+│ └── Categories → Individual sounds
+└── Tab 3: "Now Playing" (Push CPNowPlayingTemplate.shared)
+```
+
+**2. Core Components Needed:**
+
+- CarPlaySceneDelegate.swift - Scene lifecycle management
+- CarPlayInterface.swift - Template creation and management
+- CarPlay entitlements configuration
+- Info.plist scene configuration
+- Integration with existing AudioManager
+
+**3. Key Features to Implement:**
+
+**Phase 1 - Basic Integration:**
+
+- Request audio entitlement from Apple
+- Set up scene configuration in Info.plist
+- Create basic preset list with playback
+- Integrate with AudioManager for sound control
+- Update MPNowPlayingInfoCenter
+
+**Phase 2 - Enhanced Features:**
+
+- Add tab bar navigation
+- Implement sound browsing with categories
+- Add Now Playing template support
+- Show playing indicators on active items
+- Handle audio session management
+
+**Phase 3 - Advanced Features:**
+
+- Siri integration with INPlayMediaIntent
+- Favorite presets grid view
+- Empty states and error handling
+- Dark mode support
+- State persistence between sessions
+
+### Critical Implementation Notes
+
+**1. Audio Requirements:**
+
+- Must work when iPhone is locked
+- Proper audio session management (deactivate when not playing)
+- Integration with system Now Playing controls
+- Handle audio interruptions gracefully
+
+**2. UI Constraints:**
+
+- Limited to system templates (no custom UI)
+- Maximum 5 navigation levels for audio apps
+- Runtime limits on items/sections (check maximumItemCount)
+- Modal alerts should be minimal for safety
+
+**3. Testing Considerations:**
+
+- Use CarPlay Simulator for development
+- Test on physical CarPlay system for:
+ - Locked phone functionality
+ - Siri integration
+ - Audio ducking behavior
+ - Different screen sizes
+
+**4. User Experience:**
+
+- Quick access to presets via list or grid
+- Clear indication of what's currently playing
+- Simple navigation appropriate for driving
+- Voice control for hands-free operation
+
+This implementation would provide Blankie users with a safe, intuitive way to control their ambient soundscapes while driving, fully integrated with CarPlay's audio system.
+
+---
+
+## 15. api-reference/templates/alerts/cpactionsheettemplate.md
+
+**Key Points:**
+
+- Modal template for displaying multiple action options
+- Similar to CPAlertTemplate but for action sheets
+- Must present modally with presentTemplate()
+- User dismisses via button selection
+- Available since iOS 12.0
+
+**Creating Action Sheets:**
+
+```swift
+let actionSheet = CPActionSheetTemplate(
+ title: "Choose an Option",
+ message: "Select what you'd like to do",
+ actions: [
+ CPAlertAction(title: "Option 1", style: .default) { _ in
+ // Handle option 1
+ },
+ CPAlertAction(title: "Option 2", style: .default) { _ in
+ // Handle option 2
+ },
+ CPAlertAction(title: "Cancel", style: .cancel) { _ in
+ // Handle cancel
+ }
+ ]
+)
+interfaceController.presentTemplate(actionSheet, animated: true)
+```
+
+**Properties:**
+
+- title - optional title string
+- message - optional descriptive message
+- actions - array of CPAlertAction objects
+
+**Relevant for Blankie:**
+
+- Use for multiple choice scenarios (e.g., "Choose preset to delete")
+- Good for settings options (e.g., "Select timer duration")
+- Present options when multiple actions available
+- Keep options minimal for driving safety
+
+---
+
+## 16. api-reference/templates/alerts/cpalertaction.md
+
+**Key Points:**
+
+- Class that represents a button/action in alerts and action sheets
+- Used with both CPAlertTemplate and CPActionSheetTemplate
+- Has title, style, and handler closure
+- Available since iOS 12.0
+
+**Creating Actions:**
+
+```swift
+// Standard action
+let okAction = CPAlertAction(title: "OK", style: .default) { action in
+ // Handle OK tap
+}
+
+// Cancel action
+let cancelAction = CPAlertAction(title: "Cancel", style: .cancel) { action in
+ // Handle cancel
+}
+
+// Destructive action (appears in red)
+let deleteAction = CPAlertAction(title: "Delete", style: .destructive) { action in
+ // Handle delete
+}
+```
+
+**Styles:**
+
+- .default - standard action button
+- .cancel - cancel button (typically dismisses)
+- .destructive - destructive action (red color)
+
+**Additional Properties:**
+
+- color - custom color for button (iOS 14+)
+- handler - closure called when tapped
+
+**Relevant for Blankie:**
+
+- Use for all alert and action sheet buttons
+- Choose appropriate style for action type
+- Keep action titles short and clear
+- Destructive style for delete operations
+
+---
+
+## 17. api-reference/types/classes/cpbutton.md
+
+**Key Points:**
+
+- Base class for buttons that display an image
+- Used to provide template actions
+- Has specialized subclasses for common actions
+- Available since iOS 14.0
+
+**Creating Buttons:**
+
+```swift
+let button = CPButton(image: myImage) { button in
+ // Handle button tap
+}
+```
+
+**Properties:**
+
+- image - button's image (check CPButtonMaximumImageSize)
+- title - optional title string
+- isEnabled - enable/disable state
+- handler - closure called on tap
+
+**Important:**
+
+- CPButtonMaximumImageSize defines max image dimensions
+- Framework provides subclasses like CPContactCallButton (not for audio apps)
+- Template manages button appearance
+
+**Relevant for Blankie:**
+
+- Could use for custom controls in templates
+- Consider for specialized actions beyond standard buttons
+- Check if needed for Now Playing template customization
+- Most use cases covered by template-specific button types
+
+---
+
+## 18. api-reference/types/classes/cpimageset.md
+
+**Key Points:**
+
+- Provides light and dark versions of images
+- CarPlay defaults to dark appearance in most vehicles
+- Automatically switches between appearances
+- Available since iOS 12.0
+
+**Creating Image Sets:**
+
+```swift
+let imageSet = CPImageSet(
+ lightContentImage: UIImage(named: "icon-light")!,
+ darkContentImage: UIImage(named: "icon-dark")!
+)
+```
+
+**Properties:**
+
+- lightContentImage - image for light UI style
+- darkContentImage - image for dark UI style
+
+**Usage:**
+
+- Use wherever CarPlay templates accept images
+- Ensures proper appearance in both light/dark modes
+- System automatically selects appropriate image
+
+**Relevant for Blankie:**
+
+- Use for all icons in CarPlay interface
+- Create light/dark versions of preset icons
+- Important for grid buttons and list item images
+- Ensures visibility in all lighting conditions
+
+---
+
+## 19. api-reference/types/enums/cpnowplayingmode.md
+
+**Key Points:**
+
+- Base class for Now Playing modes
+- Available in iOS 18.4+ (very new)
+- Has default mode that uses system now playing info center
+- Limited documentation available
+
+**Available Modes:**
+
+- .default - uses shared MPNowPlayingInfoCenter
+
+**Notes:**
+
+- Very new API (iOS 18.4+)
+- Blankie targets iOS 16+ so this won't be available
+- Seems to be base class for sports mode (CPNowPlayingModeSports)
+
+**Relevant for Blankie:**
+
+- Not usable due to iOS version requirements
+- Standard Now Playing template will work fine
+- No need to implement custom modes
+
+---
+
+## 20. api-reference/protocols/cpbarbuttonproviding.md
+
+**Key Points:**
+
+- Protocol for templates that can show navigation bar buttons
+- Provides back button, leading and trailing bar buttons
+- You don't adopt this protocol - use templates that conform to it
+- Root templates of tab bar don't show bar buttons
+- Now Playing template can't have bar buttons (throws exception)
+
+**Properties:**
+
+- backButton - custom back button
+- leadingNavigationBarButtons - array of left-side buttons
+- trailingNavigationBarButtons - array of right-side buttons
+
+**Button Types:**
+
+- CPBarButton - standard bar button
+- CPMessageComposeBarButton - activates Siri for messages (not for audio apps)
+
+**Important Notes:**
+
+- List and Grid templates conform to this protocol
+- Tab bar's root templates can't use bar buttons
+- System manages back button in navigation hierarchy
+
+**Relevant for Blankie:**
+
+- Can add buttons to CPListTemplate views (e.g., "Add Preset" button)
+- Useful for actions in preset/sound lists
+- Remember tab bar root templates can't have bar buttons
+- Consider for secondary navigation levels only
+
+---
+
+## 21. api-reference/protocols/cptemplate.md
+
+**Key Points:**
+
+- Abstract base class for all CarPlay templates
+- Don't subclass or use directly - use prebuilt templates
+- Provides common functionality for all templates
+- Available since iOS 12.0
+
+**Common Properties:**
+
+- userInfo - custom data to associate with template
+- tabTitle - short title for tab bar
+- tabImage - image for tab bar
+- tabSystemItem - system-provided tab items
+- showsTabBadge - indicator badge on tab
+
+**Tab System Items:**
+
+- Standard UITabBarItem.SystemItem values
+- Examples: .favorites, .more, .featured, etc.
+
+**Usage:**
+
+- All templates (List, Grid, TabBar, etc.) inherit from this
+- Tab-related properties only used when template is in tab bar
+- userInfo useful for tracking template state/data
+
+**Relevant for Blankie:**
+
+- Set tabTitle and tabImage for templates in tab bar
+- Use showsTabBadge to indicate active sounds
+- Store preset/sound data in userInfo
+- Consider system items if they fit (e.g., .favorites for presets)
+
+---
+
+## 22. api-reference/scenes/cptemplateapplicationscene.md
+
+**Key Points:**
+
+- The CarPlay scene class that manages app's UI
+- Controls interface controller and window (navigation apps only)
+- Must be specified in Info.plist configuration
+- Available since iOS 13.0
+
+**Key Properties:**
+
+- delegate - receives lifecycle events (CPTemplateApplicationSceneDelegate)
+- interfaceController - manages templates and UI
+- carWindow - window for drawing (navigation apps only)
+- contentStyle - current UI style (light/dark)
+
+**Info.plist Configuration:**
+
+- Must specify UISceneClassName as CPTemplateApplicationScene
+- Pairs with scene delegate class name
+- System creates scene instances automatically
+
+**Important Notes:**
+
+- Audio apps only use interface controller (no window access)
+- Navigation apps get window for map drawing
+- Scene manages display on CarPlay screen
+- Handles lifecycle as user interacts
+
+**Relevant for Blankie:**
+
+- This is the scene class to specify in Info.plist
+- Audio apps won't access carWindow property
+- Use interfaceController for all UI management
+- Scene delegate handles connection/disconnection
+
+---
+
+## 23. api-reference/other/cpsessionconfiguration.md
+
+**Key Points:**
+
+- Provides vehicle properties and configuration info
+- Determines UI limits imposed by vehicle
+- Tracks content style based on ambient light
+- Available since iOS 12.0
+
+**Key Properties:**
+
+- contentStyle - current content style (light/dark)
+- limitedUserInterfaces - bit mask of UI limitations
+- delegate - receives notifications about changes
+
+**UI Limitations:**
+
+- Some vehicles limit keyboard display
+- May restrict list lengths
+- Check these to adjust UI accordingly
+
+**Content Style:**
+
+- CPContentStyle struct indicates style
+- Vehicle selects based on ambient light
+- Different from standard light/dark mode
+
+**Usage:**
+
+- Create with delegate to monitor changes
+- Check limitations before showing certain UI
+- Adapt to vehicle-specific constraints
+
+**Relevant for Blankie:**
+
+- Check list length limits for presets/sounds
+- Monitor content style changes
+- Adapt UI based on vehicle restrictions
+- May need to paginate long lists
+
+---
+
+## 24. api-reference/other/carplayerrordomain.md
+
+**Key Points:**
+
+- Global string constant for CarPlay error domain
+- Used for identifying CarPlay-specific errors
+- Available since iOS 12.0
+- Simple constant definition
+
+**Usage:**
+
+- Check error domain when handling errors
+- Compare with NSError domain property
+- Helps identify CarPlay-specific issues
+
+**Relevant for Blankie:**
+
+- Use for error handling in CarPlay code
+- Check when template operations fail
+- Helpful for debugging CarPlay issues
+
+---
+
+## Final Summary
+
+I've reviewed 24 CarPlay documentation files relevant to Blankie. Here's what I found:
+
+### Essential Files Read
+
+1. All getting started guides (4 files)
+2. Music app integration guide (most relevant)
+3. All audio templates (CPNowPlayingTemplate)
+4. All general templates (List, Grid, TabBar)
+5. All alert templates and actions
+6. Key types (CPButton, CPImageSet)
+7. Key protocols (CPBarButtonProviding, CPTemplate)
+8. Scene and delegate documentation
+9. Session configuration for vehicle limits
+10. Error domain constant
+
+### Files Skipped (Not Relevant for Audio Apps)
+
+- Navigation-specific templates and types (12+ files)
+- Communication templates (2 files)
+- Parking/EV/Food ordering templates (3 files)
+- Sports streaming features (5 files)
+- Instrument cluster features (4 files)
+- Deprecated symbols
+
+### Key Implementation Requirements for Blankie
+
+1. Request audio entitlement from Apple
+2. Configure Info.plist with scene settings
+3. Implement CarPlaySceneDelegate
+4. Use CPTabBarTemplate as root
+5. Integrate with existing AudioManager
+6. Update MPNowPlayingInfoCenter
+7. Handle locked phone state
+8. Test with physical CarPlay system
+
+The documentation provides everything needed to implement a fully-featured CarPlay interface for Blankie's ambient sound mixing functionality.
+
+---
+
+## 25. api-reference/other/carplay-constants.md
+
+**Key Points:**
+
+- Lists available constants for CarPlay
+- CPGridTemplateMaximumItems - maximum buttons in grid template
+- CPMaximumListSectionImageSize - maximum image size in list sections
+
+**Relevant for Blankie:**
+
+- Use these constants to ensure proper sizing of UI elements
+- Important for grid template (max 8 buttons shown)
+- Check image sizes for list sections
+
+---
+
+## 26. api-reference/other/carplay-enumerations.md
+
+**Key Points:**
+
+- Lists enumerations available in CarPlay
+- Most are navigation-specific (CPJunctionType, CPManeuverType, etc.)
+- CPInstrumentClusterSetting - for instrument cluster
+- CPTrafficSide - which side of road traffic drives on
+
+**Relevant for Blankie:**
+
+- None of these enumerations are relevant for audio apps
+- All are for navigation, traffic, or instrument cluster features
+
+---
+
+## Final Documentation Review Summary
+
+After reviewing all CarPlay documentation files, I've identified:
+
+Files Read: 31 total
+
+- 24 relevant files documented in detail
+- 7 additional files that were duplicates of overview.md
+
+**Key Findings:**
+
+1. **Many duplicate files** - The api-reference/other/ folder contains numerous duplicate overview pages with identical content
+
+2. **Essential Documentation for Blankie:**
+ - All getting started guides ✓
+ - Music app integration guide ✓
+ - Audio templates (CPNowPlayingTemplate) ✓
+ - General templates (List, Grid, TabBar) ✓
+ - Alert/action templates ✓
+ - Scene and delegate documentation ✓
+ - Constants and error domain ✓
+
+3. **Not Relevant for Blankie:**
+ - Navigation-specific features (70+ files)
+ - Communication templates
+ - Sports streaming features
+ - Parking/EV/Food ordering templates
+ - Instrument cluster features
+
+The comprehensive implementation plan and architecture overview in the notes above provide everything needed to implement CarPlay support for Blankie's ambient sound mixing functionality.
diff --git a/notes/CarPlayRecc.md b/notes/CarPlayRecc.md
new file mode 100644
index 0000000..46965af
--- /dev/null
+++ b/notes/CarPlayRecc.md
@@ -0,0 +1,229 @@
+# CarPlay Implementation Guide for Blankie
+
+This guide provides everything needed to implement CarPlay support in Blankie. The app is already approved for CarPlay audio entitlement.
+
+## Resources Created for This Implementation
+
+1. **CarPlayNotes.md** - Comprehensive notes from reviewing all CarPlay documentation, including code examples and implementation details
+2. **CarPlayTodo.md** - Tracking document showing which CarPlay docs were reviewed (31 files read, 24 relevant for Blankie)
+3. **This Guide** - Step-by-step implementation instructions
+
+## What to Build: 3-Tab CarPlay Interface
+
+### Core Structure
+
+```txt
+CPTabBarTemplate (Root)
+├── "Presets" Tab → CPListTemplate
+├── "Quick Mix" Tab → CPGridTemplate (8 favorite sounds)
+└── "Sounds" Tab → CPListTemplate (all sounds in solo mode)
+
+System Now Playing Button (♫) → CPNowPlayingTemplate.shared
+```
+
+### Tab 1: Presets List
+
+- Display all saved presets in a scrollable list
+- Show preset name only (keep it simple)
+- Currently playing preset shows a checkmark or highlight
+- Tapping any preset immediately plays it
+- Empty state: "No presets saved - create in iPhone app"
+- Consider adding "Recent" section at top with last 3 used presets
+
+### Tab 2: Quick Mix Grid
+
+- 8-button grid showing most popular sounds
+- Each button shows sound icon + name
+- Tapping toggles that sound on/off
+- Active sounds show highlighted state
+- Allows quick mixing without leaving the screen
+- Use these 8 sounds: Rain, Waves, Fireplace, White Noise, Wind, Stream, Birds, Coffee Shop
+
+### Tab 3: Sounds List (Solo Mode)
+
+- Scrollable list of ALL available sounds
+- Tapping any sound switches to solo mode (only that sound plays)
+- Currently playing sound shows with indicator
+- Organized alphabetically or by category
+- Each row shows sound icon + name
+
+### Now Playing (System Button)
+
+- Users access via the (♫) button in top-right corner
+- Update MPNowPlayingInfoCenter with:
+ - Title: Current preset name OR "Custom Mix"
+ - Artist: Active sound names (e.g., "Rain + Fireplace")
+ - Album: "Blankie"
+- Standard play/pause controls work with AudioManager
+
+## Implementation Steps
+
+### Step 1: Configure Entitlements
+
+Add to `Blankie-CarPlay.entitlements`:
+
+```xml
+com.apple.developer.carplay-audio
+
+```
+
+### Step 2: Update Info.plist
+
+Add to `Blankie-CarPlay.plist`:
+
+```xml
+UIApplicationSceneManifest
+
+ UIApplicationSupportsMultipleScenes
+
+ UISceneConfigurations
+
+ CPTemplateApplicationSceneSessionRoleApplication
+
+
+ UISceneClassName
+ CPTemplateApplicationScene
+ UISceneDelegateClassName
+ Blankie.CarPlaySceneDelegate
+
+
+
+
+```
+
+### Step 3: Create File Structure
+
+```txt
+Blankie/
+├── CarPlay/
+│ ├── CarPlaySceneDelegate.swift
+│ ├── CarPlayInterfaceController.swift
+│ ├── Templates/
+│ │ ├── PresetListTemplate.swift
+│ │ ├── QuickMixGridTemplate.swift
+│ │ └── SoundsListTemplate.swift
+│ └── Helpers/
+│ └── CarPlayImageProvider.swift
+```
+
+### Step 4: Implement CarPlaySceneDelegate
+
+```swift
+class CarPlaySceneDelegate: NSObject, CPTemplateApplicationSceneDelegate {
+ var interfaceController: CPInterfaceController?
+
+ func templateApplicationScene(_ scene: CPTemplateApplicationScene,
+ didConnect interfaceController: CPInterfaceController) {
+ self.interfaceController = interfaceController
+
+ // Create tabs
+ let presetsTab = createPresetsTemplate()
+ let quickMixTab = createQuickMixTemplate()
+ let soundsTab = createSoundsTemplate()
+
+ // Set root template
+ let tabBar = CPTabBarTemplate(templates: [presetsTab, quickMixTab, soundsTab])
+ interfaceController.setRootTemplate(tabBar, animated: false)
+
+ // Subscribe to AudioManager notifications
+ setupAudioManagerObservers()
+ }
+}
+```
+
+### Step 5: Key Integration Points
+
+#### Use Existing Managers
+
+- **AudioManager**: Use directly, don't create CarPlay-specific audio code
+- **PresetManager**: Read presets, handle selection
+- **Sound**: Use existing sound model and metadata
+
+#### Audio Session Requirements
+
+- Must work when iPhone is locked
+- Use `.playback` category (not `.ambient`)
+- Deactivate session when not playing
+- Handle interruptions (phone calls, Siri, navigation)
+
+#### Image Handling
+
+```swift
+// Create light/dark image sets for all sounds
+let rainIcon = CPImageSet(
+ lightContentImage: UIImage(named: "rain-carplay-light")!,
+ darkContentImage: UIImage(named: "rain-carplay-dark")!
+)
+```
+
+## Testing Checklist
+
+### Simulator Testing
+
+1. Launch CarPlay Simulator (I/O → External Displays → CarPlay)
+2. Verify app appears on home screen
+3. Test all three tabs load correctly
+4. Verify preset selection works
+5. Test Quick Mix sound toggling
+6. Verify solo mode switching
+7. Check Now Playing button shows correct info
+
+### Physical Device Testing
+
+1. Test with iPhone locked in pocket
+2. Verify audio continues during navigation
+3. Test Siri interruptions
+4. Verify phone call interruptions
+5. Test rapid preset switching
+6. Check memory usage over time
+7. Test on older devices (iPhone 12 or earlier)
+
+## Important Constraints
+
+### Do NOT Include
+
+- Preset creation/editing (too complex while driving)
+- Individual volume sliders (use system volume)
+- Timer functionality (not safe while driving)
+- Custom sound import (built-in sounds only)
+- Complex settings or preferences
+
+### Must Handle
+
+- State sync between iPhone and CarPlay
+- Proper audio session lifecycle
+- High contrast icons for all lighting
+- Single-tap interactions only
+- Clear visual feedback for all actions
+
+## Success Criteria
+
+1. **3-Second Test**: User can start their favorite preset within 3 seconds
+2. **Locked Phone**: Everything works with iPhone locked
+3. **Safe Interaction**: All primary actions require only one tap
+4. **State Sync**: CarPlay reflects current playback state immediately
+5. **Interruption Recovery**: Audio resumes properly after calls/Siri
+
+## Common Pitfalls to Avoid
+
+1. **Don't** create separate data storage for CarPlay
+2. **Don't** add complex navigation hierarchies
+3. **Don't** show alerts/errors unless absolutely critical
+4. **Don't** require text input anywhere
+5. **Don't** animate unnecessarily (distracting while driving)
+
+## Phase 2 Considerations (Future)
+
+- Siri Shortcuts: "Play my Sleep preset"
+- Widget in instrument cluster (if supported)
+- Seasonal sound suggestions
+- Most-used presets bubble to top
+
+## Questions to Answer Before Starting
+
+1. Should Quick Mix remember last state or always start fresh?
+2. How many recent presets to show (3, 5, none)?
+3. Should sound categories be used in the Sounds list?
+4. What happens if a preset references a missing sound?
+
+Remember: The goal is to make Blankie feel like a simple, safe remote control for the iPhone app. When in doubt, choose the simpler option.
diff --git a/notes/CarPlayTodo.md b/notes/CarPlayTodo.md
new file mode 100644
index 0000000..e55fe0e
--- /dev/null
+++ b/notes/CarPlayTodo.md
@@ -0,0 +1,132 @@
+# CarPlay Documentation Todo List
+
+This file tracks which CarPlay documentation files have been read and documented in CarPlayNotes.md.
+
+## Guides
+
+### Getting Started
+
+- [x] guides/getting-started/requesting-carplay-entitlements.md
+- [x] guides/getting-started/displaying-content-in-carplay.md
+- [x] guides/getting-started/using-the-carplay-simulator.md
+- [x] guides/getting-started/supporting-previous-versions-of-ios.md
+
+### Integration
+
+- [x] guides/integration/integrating-carplay-with-your-music-app.md
+- [ ] ~~guides/integration/integrating-carplay-with-your-navigation-app.md~~ (navigation entitlement only)
+- [ ] ~~guides/integration/integrating-carplay-with-your-quick-ordering-app.md~~ (quick-ordering entitlement only)
+
+## API Reference
+
+### Templates
+
+#### Audio
+
+- [x] api-reference/templates/audio/cpnowplayingtemplate.md
+
+#### General
+
+- [x] api-reference/templates/general/cplisttemplate.md
+- [x] api-reference/templates/general/cpgridtemplate.md
+- [x] api-reference/templates/general/cptabbartemplate.md
+- [ ] ~~api-reference/templates/general/cpinformationtemplate.md~~ (not available for audio apps - line 37)
+- [ ] ~~api-reference/templates/general/cptextbutton.md~~ (only for CPPointOfInterest and CPInformationTemplate)
+
+#### Alerts
+
+- [x] api-reference/templates/alerts/cpalerttemplate.md
+- [x] api-reference/templates/alerts/cpactionsheettemplate.md
+- [x] api-reference/templates/alerts/cpalertaction.md
+
+#### Navigation
+
+- [ ] ~~api-reference/templates/navigation/cpmaptemplate.md~~ (navigation entitlement only)
+- [ ] ~~api-reference/templates/navigation/cppointofinteresttemplate.md~~ (parking/EV/food entitlement only)
+- [ ] ~~api-reference/templates/navigation/cpsearchtemplate.md~~ (navigation entitlement only)
+
+#### Communication
+
+- [ ] ~~api-reference/templates/communication/cpcontacttemplate.md~~ (communication entitlement only)
+- [ ] ~~api-reference/templates/communication/cpvoicecontroltemplate.md~~ (navigation entitlement only)
+
+### Types
+
+#### Classes
+
+- [x] api-reference/types/classes/cpbutton.md
+- [x] api-reference/types/classes/cpimageset.md
+- [ ] ~~api-reference/types/classes/cplane.md~~ (navigation only)
+- [ ] ~~api-reference/types/classes/cplaneguidance.md~~ (navigation only)
+- [ ] ~~api-reference/types/classes/cpmaneuver.md~~ (navigation only)
+- [ ] ~~api-reference/types/classes/cprouteinformation.md~~ (navigation only)
+
+#### Enums
+
+- [ ] ~~api-reference/types/enums/cpjunctiontype.md~~ (navigation only)
+- [ ] ~~api-reference/types/enums/cplanestatus.md~~ (navigation only)
+- [ ] ~~api-reference/types/enums/cpmaneuverstate.md~~ (navigation only)
+- [ ] ~~api-reference/types/enums/cpmaneuvertype.md~~ (navigation only)
+- [x] api-reference/types/enums/cpnowplayingmode.md
+
+### Protocols
+
+- [x] api-reference/protocols/cpbarbuttonproviding.md
+- [ ] ~~api-reference/protocols/cpinstrumentclustercontrollerdelegate.md~~ (instrument cluster only)
+- [x] api-reference/protocols/cptemplate.md
+
+### Scenes
+
+- [x] api-reference/scenes/cptemplateapplicationscene.md
+- [ ] ~~api-reference/scenes/cptemplateapplicationdashboardscene.md~~ (navigation only)
+- [ ] ~~api-reference/scenes/cptemplateapplicationinstrumentclusterscene.md~~ (instrument cluster only)
+
+### Other
+
+- [x] api-reference/other/overview.md
+- [x] api-reference/other/index.md (duplicate of overview.md)
+- [x] api-reference/other/topics.md (another duplicate overview)
+- [x] api-reference/other/app-main.md (yet another duplicate overview)
+- [x] api-reference/other/Reference.md (duplicate overview - same as overview.md)
+- [x] api-reference/other/Audio.md (duplicate overview - same as overview.md)
+- [x] api-reference/other/Actions-and-Alerts.md (duplicate overview - same as overview.md)
+- [x] api-reference/other/CarPlay-Integration.md (duplicate overview - same as overview.md)
+- [x] api-reference/other/Classes.md (duplicate overview - same as overview.md)
+- [ ] ~~api-reference/other/Communication.md~~ (communication entitlement only)
+- [ ] ~~api-reference/other/General-Purpose-Templates.md~~
+- [ ] ~~api-reference/other/Instrument-cluster.md~~ (navigation only)
+- [ ] ~~api-reference/other/Location-and-Information.md~~ (parking/EV/food only)
+- [ ] ~~api-reference/other/Maneuvers.md~~ (navigation only)
+- [ ] ~~api-reference/other/Navigation.md~~ (navigation only)
+- [ ] ~~api-reference/other/Related-Types.md~~
+- [ ] ~~api-reference/other/Routes-lanes-and-junctions.md~~ (navigation only)
+- [x] api-reference/other/ac-gn-menustate.md (duplicate overview - same as overview.md)
+- [x] api-reference/other/carplay-constants.md
+- [x] api-reference/other/carplay-enumerations.md
+- [x] api-reference/other/carplayerrordomain.md
+- [ ] ~~api-reference/other/cpinstrumentclustercontroller.md~~ (navigation only)
+- [ ] ~~api-reference/other/cpnowplayingmodesports.md~~ (sports streaming only)
+- [ ] ~~api-reference/other/cpnowplayingsportsclock.md~~ (sports streaming only)
+- [ ] ~~api-reference/other/cpnowplayingsportseventstatus.md~~ (sports streaming only)
+- [ ] ~~api-reference/other/cpnowplayingsportsteam.md~~ (sports streaming only)
+- [ ] ~~api-reference/other/cpnowplayingsportsteamlogo.md~~ (sports streaming only)
+- [x] api-reference/other/cpsessionconfiguration.md
+- [ ] ~~api-reference/other/cptemplateapplicationdashboardscenedelegate.md~~ (navigation only)
+- [ ] ~~api-reference/other/cptemplateapplicationinstrumentclusterscenedelegate.md~~ (navigation only)
+- [x] api-reference/other/cptemplateapplicationscenedelegate.md
+
+## Deprecated
+
+- [ ] ~~deprecated/deprecated-symbols.md~~ (not relevant for new implementation)
+
+## Top Level
+
+- [x] carplay/README.md
+
+---
+
+## Notes
+
+- Files marked with ~~strikethrough~~ are not relevant for Blankie (audio app)
+- Files marked with [x] have been read and documented
+- Files marked with [ ] still need to be reviewed
diff --git a/RELEASING.md b/notes/RELEASE.md
similarity index 100%
rename from RELEASING.md
rename to notes/RELEASE.md
diff --git a/blanki18n.swift b/scripts/blanki18n.swift
similarity index 95%
rename from blanki18n.swift
rename to scripts/blanki18n.swift
index 44e4a4d..c3b55a4 100755
--- a/blanki18n.swift
+++ b/scripts/blanki18n.swift
@@ -48,7 +48,8 @@ func parseCSV(data: String) -> [CSVRow] {
func getFilePath() -> String {
guard CommandLine.arguments.count > 1 else {
print("Error: Please provide a translation file path")
- print("Usage: ./blanki8n.swift path/to/translation.[json|csv] [language_code] [--preserve-states]")
+ print(
+ "Usage: ./blanki8n.swift path/to/translation.[json|csv] [language_code] [--preserve-states]")
exit(1)
}
@@ -78,13 +79,15 @@ func parseJSON(data: Data) -> [CSVRow] {
var rows: [CSVRow] = []
guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
- let strings = json["strings"] as? [String: [String: Any]] else {
+ let strings = json["strings"] as? [String: [String: Any]]
+ else {
return rows
}
for (key, value) in strings {
if let target = value["target"] as? String,
- let state = value["state"] as? String {
+ let state = value["state"] as? String
+ {
rows.append(CSVRow(key: key, target: target, state: state))
}
}
@@ -130,7 +133,8 @@ func readXCStringsFile() -> (json: [String: Any], strings: [String: [String: Any
}
func updateTranslations(
- in strings: [String: [String: Any]], with translations: [CSVRow], for langCode: String, preserveStates: Bool
+ in strings: [String: [String: Any]], with translations: [CSVRow], for langCode: String,
+ preserveStates: Bool
) -> ([String: [String: Any]], Int) {
var updatedStrings = strings
var updatedCount = 0
diff --git a/scripts/convert-audio.sh b/scripts/convert-audio.sh
new file mode 100755
index 0000000..ad163f2
--- /dev/null
+++ b/scripts/convert-audio.sh
@@ -0,0 +1,176 @@
+#!/bin/bash
+
+# Convert audio files to high-quality m4a (AAC) format
+# Usage: ./convert-audio.sh [input_format] [bitrate] [directory]
+# Example: ./convert-audio.sh wav 192k
+# Example: ./convert-audio.sh mp3 256k /path/to/audio/files
+# Example: ./convert-audio.sh * 192k .
+# Default: converts all audio formats to m4a at 192k in current directory
+
+# Check if ffmpeg is installed
+if ! command -v ffmpeg &> /dev/null; then
+ echo "Error: ffmpeg is not installed"
+ echo "Install it using: brew install ffmpeg"
+ exit 1
+fi
+
+# Default values
+INPUT_FORMAT="${1:-*}" # Default: all supported formats
+BITRATE="${2:-192k}" # Default: 192k
+WORK_DIR="${3:-.}" # Default: current directory
+
+# If no directory specified and we're in the Blankie project, use the sounds directory
+if [ "$3" = "" ] && [ -d "Blankie/Resources/Sounds" ]; then
+ WORK_DIR="Blankie/Resources/Sounds"
+elif [ "$3" = "" ] && [ -d "../Blankie/Resources/Sounds" ]; then
+ WORK_DIR="../Blankie/Resources/Sounds"
+elif [ "$3" = "" ] && [ -d "./Blankie/Resources/Sounds" ]; then
+ WORK_DIR="./Blankie/Resources/Sounds"
+fi
+
+# Supported input formats
+SUPPORTED_FORMATS="wav mp3 aac aiff flac ogg"
+
+echo "Audio to M4A Converter"
+echo "====================="
+echo "Input format: $INPUT_FORMAT"
+echo "Output format: m4a (AAC)"
+echo "Bitrate: $BITRATE"
+echo "Directory: $(realpath "$WORK_DIR")"
+echo
+
+cd "$WORK_DIR" || { echo "Error: Cannot access directory $WORK_DIR"; exit 1; }
+
+# Function to determine audio quality priority (higher number = better quality)
+get_format_priority() {
+ case "$1" in
+ "wav"|"aiff"|"flac") echo 4 ;; # Lossless formats
+ "m4a"|"aac") echo 3 ;; # High-quality lossy
+ "ogg") echo 2 ;; # Medium-quality lossy
+ "mp3") echo 1 ;; # Lower-quality lossy
+ *) echo 0 ;; # Unknown
+ esac
+}
+
+# Function to convert a single file to m4a
+convert_file() {
+ local input_file="$1"
+ local base_name="${input_file%.*}"
+ local input_ext="${input_file##*.}"
+ local output_file="${base_name}.m4a"
+
+ # Skip if already m4a
+ if [ "$input_ext" = "m4a" ]; then
+ echo "⏭️ Skipping $input_file (already in m4a format)"
+ return
+ fi
+
+ # Smart handling of existing output files
+ if [ -f "$output_file" ]; then
+ # Get priority of current input vs existing output's likely source
+ input_priority=$(get_format_priority "$input_ext")
+
+ # Check if there are other source files that could have created the existing m4a
+ existing_sources=""
+ for ext in wav aiff flac mp3 ogg aac; do
+ if [ -f "${base_name}.${ext}" ] && [ "${base_name}.${ext}" != "$input_file" ]; then
+ existing_sources="$existing_sources $ext"
+ fi
+ done
+
+ if [ -n "$existing_sources" ]; then
+ # Find the highest priority among existing sources
+ max_existing_priority=0
+ for ext in $existing_sources; do
+ priority=$(get_format_priority "$ext")
+ if [ $priority -gt $max_existing_priority ]; then
+ max_existing_priority=$priority
+ fi
+ done
+
+ if [ $input_priority -gt $max_existing_priority ]; then
+ echo "🔄 Upgrading $output_file (better source: $input_ext vs existing sources)"
+ elif [ $input_priority -eq $max_existing_priority ]; then
+ echo "⚠️ $output_file exists with same quality source, overwriting anyway"
+ else
+ echo "⬇️ $output_file exists with better source, but converting anyway"
+ fi
+ else
+ echo "🔄 Overwriting existing $output_file"
+ fi
+ fi
+
+ echo "Converting $input_file to m4a..."
+
+ # Convert to m4a with AAC codec
+ ffmpeg -i "$input_file" -c:a aac -b:a "$BITRATE" -ar 44100 -ac 2 "$output_file" -hide_banner -loglevel error
+
+ if [ $? -eq 0 ]; then
+ # Get file sizes
+ input_size=$(ls -lh "$input_file" | awk '{print $5}')
+ output_size=$(ls -lh "$output_file" | awk '{print $5}')
+
+ echo "✅ Converted successfully"
+ echo " Original: $input_size → Output: $output_size"
+
+ # Calculate size ratio
+ input_bytes=$(stat -f%z "$input_file" 2>/dev/null || stat -c%s "$input_file" 2>/dev/null)
+ output_bytes=$(stat -f%z "$output_file" 2>/dev/null || stat -c%s "$output_file" 2>/dev/null)
+ if [ -n "$input_bytes" ] && [ -n "$output_bytes" ]; then
+ if [ "$input_bytes" -gt "$output_bytes" ]; then
+ ratio=$(echo "scale=1; $input_bytes / $output_bytes" | bc)
+ echo " Compression ratio: ${ratio}:1"
+ else
+ ratio=$(echo "scale=1; $output_bytes / $input_bytes" | bc)
+ echo " Size increase: ${ratio}x"
+ fi
+ fi
+
+ # Analyze the output file
+ echo -n " Output info: "
+ ffprobe -v quiet -show_streams -select_streams a:0 "$output_file" | grep -E "(codec_name|bit_rate|sample_rate|channels)" | tr '\n' ' ' | sed 's/codec_name=/codec:/g' | sed 's/bit_rate=/bitrate:/g' | sed 's/sample_rate=/sr:/g' | sed 's/channels=/ch:/g'
+ echo
+ else
+ echo "❌ Failed to convert $input_file"
+ fi
+ echo
+}
+
+# Convert files based on input format
+if [ "$INPUT_FORMAT" = "*" ]; then
+ # Convert all supported formats to m4a
+ echo "Converting all supported audio formats to m4a..."
+ echo
+
+ for format in $SUPPORTED_FORMATS; do
+ for file in *."$format"; do
+ if [ -f "$file" ]; then
+ convert_file "$file"
+ fi
+ done
+ done
+else
+ # Convert specific format to m4a
+ echo "Converting $INPUT_FORMAT files to m4a..."
+ echo
+
+ found_files=false
+ for file in *."$INPUT_FORMAT"; do
+ if [ -f "$file" ]; then
+ convert_file "$file"
+ found_files=true
+ fi
+ done
+
+ if [ "$found_files" = false ]; then
+ echo "No $INPUT_FORMAT files found in $(pwd)"
+ fi
+fi
+
+echo "Conversion complete!"
+echo
+echo "Tips:"
+echo "- To remove source files after verifying conversions:"
+echo " rm *.$INPUT_FORMAT"
+echo "- To replace existing files with converted versions:"
+echo " for f in *-converted.m4a; do mv \"\$f\" \"\${f%-converted.m4a}.m4a\"; done"
\ No newline at end of file
diff --git a/scripts/prepare_loop.sh b/scripts/prepare_loop.sh
new file mode 100755
index 0000000..185c176
--- /dev/null
+++ b/scripts/prepare_loop.sh
@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+ cat <<'USAGE'
+Usage: prepare_loop.sh [input-file] [options]
+
+If no input file is provided, processes all video files in Blankie/Assets/AnimatedArtwork
+that don't already have .mov and .jpg versions.
+
+Options:
+ -o, --output-dir DIR Directory for the generated files (default: same as input)
+ -n, --name NAME Base name for outputs (default: input file name without extension)
+ -w, --width PIXELS Output width in pixels (default: 1080)
+ -h, --height PIXELS Output height in pixels (default: 1440, 3:4 aspect ratio)
+ --crf VALUE Constant Rate Factor (default: 20)
+ --anchor POS Crop anchor: center, top, bottom, left, right,
+ bottom-center, top-center (default: center)
+ --help Show this help and exit
+
+The script crops the input to a 3:4 portrait aspect ratio (for iPhone lock screens),
+scales to the requested size, encodes to the chosen codec, and writes:
+ .mov (loop video)
+ .jpg (first-frame preview, 3:4 portrait)
+ Square.jpg (first-frame preview, 1:1 square)
+USAGE
+}
+
+if ! command -v ffmpeg >/dev/null 2>&1; then
+ echo "❌ ffmpeg is required but not found in PATH" >&2
+ exit 1
+fi
+
+to_lower() {
+ printf '%s' "$1" | tr '[:upper:]' '[:lower:]'
+}
+
+INPUT=""
+OUTPUT_DIR=""
+NAME=""
+WIDTH=1080
+HEIGHT=1440
+CRF="20"
+ANCHOR="center"
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ -o|--output-dir)
+ OUTPUT_DIR="$2"; shift 2;;
+ -n|--name)
+ NAME="$2"; shift 2;;
+ -w|--width)
+ WIDTH="$2"; shift 2;;
+ -h|--height)
+ HEIGHT="$2"; shift 2;;
+ --crf)
+ CRF="$2"; shift 2;;
+ --anchor)
+ ANCHOR="$(to_lower "$2")"; shift 2;;
+ --help)
+ usage; exit 0;;
+ -*)
+ echo "Unknown option: $1" >&2
+ usage; exit 1;;
+ *)
+ if [[ -z "$INPUT" ]]; then
+ INPUT="$1"; shift
+ else
+ echo "Only one input file may be specified." >&2
+ usage; exit 1
+ fi;;
+ esac
+done
+
+# If no input provided, process all unprocessed files in AnimatedArtwork
+if [[ -z "$INPUT" ]]; then
+ SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+ PROJECT_DIR=$(dirname "$SCRIPT_DIR")
+ ARTWORK_DIR="$PROJECT_DIR/Blankie/Assets/AnimatedArtwork"
+
+ if [[ ! -d "$ARTWORK_DIR" ]]; then
+ echo "❌ AnimatedArtwork directory not found: $ARTWORK_DIR" >&2
+ exit 1
+ fi
+
+ # Find all video files that don't have all three outputs (.mov, .jpg, and Square.jpg)
+ # Only use .mp4 files as source (skip .mov files - they are outputs)
+ FILES_TO_PROCESS=()
+ while IFS= read -r -d '' file; do
+ basename=$(basename "$file")
+ name="${basename%.*}"
+ ext="${basename##*.}"
+
+ # Only process .mp4 files (and other source formats), skip .mov files
+ if [[ "$ext" == "mov" ]]; then
+ continue
+ fi
+
+ # Check if all three outputs exist
+ if [[ ! -f "$ARTWORK_DIR/$name.mov" ]] || [[ ! -f "$ARTWORK_DIR/$name.jpg" ]] || [[ ! -f "$ARTWORK_DIR/${name}Square.jpg" ]]; then
+ FILES_TO_PROCESS+=("$file")
+ fi
+ done < <(find "$ARTWORK_DIR" -type f \( -name "*.mp4" -o -name "*.avi" -o -name "*.mkv" \) ! -name ".*" -print0 | sort -z)
+
+ if [[ ${#FILES_TO_PROCESS[@]} -eq 0 ]]; then
+ echo "✅ All files in $ARTWORK_DIR already have .mov, .jpg, and Square.jpg versions"
+ exit 0
+ fi
+
+ echo "🎬 Found ${#FILES_TO_PROCESS[@]} file(s) to process:"
+ for f in "${FILES_TO_PROCESS[@]}"; do
+ echo " - $(basename "$f")"
+ done
+ echo ""
+
+ # Process each file
+ for file in "${FILES_TO_PROCESS[@]}"; do
+ basename=$(basename "$file")
+ name="${basename%.*}"
+
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+ echo "📹 Processing: $basename"
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+ # Recursively call this script with the file as input
+ "$0" "$file" -w "$WIDTH" -h "$HEIGHT" --crf "$CRF" --anchor "$ANCHOR"
+
+ echo ""
+ done
+
+ echo "🎉 Batch processing complete!"
+ exit 0
+fi
+
+if [[ ! -f "$INPUT" ]]; then
+ echo "❌ Input file not found: $INPUT" >&2
+ exit 1
+fi
+
+INPUT=$(realpath "$INPUT")
+INPUT_DIR=$(dirname "$INPUT")
+
+if [[ -z "$OUTPUT_DIR" ]]; then
+ OUTPUT_DIR="$INPUT_DIR"
+else
+ mkdir -p "$OUTPUT_DIR"
+fi
+
+OUTPUT_DIR=$(realpath "$OUTPUT_DIR")
+
+if [[ -z "$NAME" ]]; then
+ NAME=$(basename "$INPUT")
+ NAME="${NAME%.*}"
+fi
+
+# H.264 only for maximum compatibility
+VCODEC="libx264"
+TAG="avc1"
+CODEC_PARAMS=(-x264-params "keyint=60:min-keyint=60:scenecut=0")
+
+case "$ANCHOR" in
+ center|top|bottom|left|right|top-center|bottom-center) ;;
+ *)
+ echo "❌ Unsupported anchor: $ANCHOR (use center, top, bottom, left, right)" >&2
+ exit 1
+ ;;
+esac
+
+# Calculate 3:4 crop dimensions (portrait)
+# crop_w = min(iw, ih * 3/4)
+# crop_h = crop_w * 4/3
+CROP_W="min(iw\\,ih*3/4)"
+CROP_H="(${CROP_W})*4/3"
+
+# Default center positioning
+base_x="((iw-${CROP_W})/2)"
+base_y="((ih-${CROP_H})/2)"
+
+anchor_x="$base_x"
+anchor_y="$base_y"
+
+case "$ANCHOR" in
+ left)
+ anchor_x="0" ;;
+ right)
+ anchor_x="(iw-${CROP_W})" ;;
+ top)
+ anchor_y="0" ;;
+ bottom)
+ anchor_y="(ih-${CROP_H})" ;;
+ top-center)
+ anchor_y="((ih-${CROP_H})/4)" ;;
+ bottom-center)
+ anchor_y="(3*(ih-${CROP_H})/4)" ;;
+esac
+
+LOOP_PATH="$OUTPUT_DIR/${NAME}.mov"
+PREVIEW_PATH="$OUTPUT_DIR/${NAME}.jpg"
+SQUARE_PREVIEW_PATH="$OUTPUT_DIR/${NAME}Square.jpg"
+
+FILTER="crop=${CROP_W}:${CROP_H}:${anchor_x}:${anchor_y},scale=${WIDTH}:${HEIGHT},setsar=1"
+
+echo "🎞️ Encoding loop → $LOOP_PATH"
+ffmpeg -hide_banner -y \
+ -i "$INPUT" \
+ -vf "$FILTER" \
+ -an \
+ -c:v "$VCODEC" \
+ -preset medium \
+ -crf "$CRF" \
+ "${CODEC_PARAMS[@]}" \
+ -pix_fmt yuv420p \
+ -tag:v "$TAG" \
+ -movflags +faststart \
+ "$LOOP_PATH"
+
+echo "🖼️ Extracting preview → $PREVIEW_PATH"
+ffmpeg -hide_banner -y \
+ -i "$LOOP_PATH" \
+ -vf "select=eq(n\\,0)" \
+ -frames:v 1 \
+ -update 1 \
+ "$PREVIEW_PATH"
+
+# Calculate square crop dimensions (1:1 aspect ratio)
+SQUARE_SIZE="min(iw\\,ih)"
+SQUARE_X="((iw-${SQUARE_SIZE})/2)"
+SQUARE_Y="((ih-${SQUARE_SIZE})/2)"
+SQUARE_FILTER="crop=${SQUARE_SIZE}:${SQUARE_SIZE}:${SQUARE_X}:${SQUARE_Y},scale=${WIDTH}:${WIDTH},setsar=1"
+
+echo "🔲 Extracting square preview → $SQUARE_PREVIEW_PATH"
+ffmpeg -hide_banner -y \
+ -i "$INPUT" \
+ -vf "${SQUARE_FILTER},select=eq(n\\,0)" \
+ -frames:v 1 \
+ -update 1 \
+ "$SQUARE_PREVIEW_PATH"
+
+echo "✅ Done. Generated:"
+echo " $LOOP_PATH"
+echo " $PREVIEW_PATH"
+echo " $SQUARE_PREVIEW_PATH"
diff --git a/scripts/reanalyze-sounds.swift b/scripts/reanalyze-sounds.swift
new file mode 100755
index 0000000..8d3bd2e
--- /dev/null
+++ b/scripts/reanalyze-sounds.swift
@@ -0,0 +1,208 @@
+#!/usr/bin/env swift
+
+import AVFoundation
+import Foundation
+
+// This script re-analyzes all built-in sounds and outputs updated JSON values
+// Run from project root: swift scripts/reanalyze-sounds.swift
+
+// MARK: - Data Structures
+
+struct SoundData: Codable {
+ let defaultOrder: Int
+ let title: String
+ let systemIconName: String
+ let fileName: String
+ let author: String?
+ let authorUrl: String?
+ let license: String
+ let soundUrl: String?
+ let soundName: String
+ let description: String
+ let note: String?
+ let lufs: Float?
+ let normalizationFactor: Float?
+}
+
+struct SoundsContainer: Codable {
+ let sounds: [SoundData]
+}
+
+// MARK: - Audio Analysis (simplified version)
+
+func analyzeLUFS(at url: URL) -> (lufs: Float, normalizationFactor: Float)? {
+ do {
+ let file = try AVAudioFile(forReading: url)
+ let format = file.processingFormat
+ let frameCount = UInt32(file.length)
+
+ guard let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: frameCount) else {
+ print("Failed to create buffer for \(url.lastPathComponent)")
+ return nil
+ }
+
+ try file.read(into: buffer)
+ buffer.frameLength = frameCount
+
+ // Simplified LUFS calculation - just using RMS as approximation
+ var totalPower: Float = 0
+ let channelCount = Int(format.channelCount)
+
+ for channel in 0.. Paths {
+ let currentDir = FileManager.default.currentDirectoryPath
+ return Paths(
+ jsonPath: "\(currentDir)/Blankie/Resources/sounds.json",
+ soundsDir: "\(currentDir)/Blankie/Resources/Sounds",
+ outputPath: "\(currentDir)/Blankie/Resources/sounds-updated.json"
+ )
+}
+
+func loadSoundsContainer(from jsonPath: String) -> SoundsContainer {
+ guard let jsonData = try? Data(contentsOf: URL(fileURLWithPath: jsonPath)) else {
+ print("Error: Could not read sounds.json at \(jsonPath)")
+ exit(1)
+ }
+
+ let decoder = JSONDecoder()
+ guard let container = try? decoder.decode(SoundsContainer.self, from: jsonData) else {
+ print("Error: Could not decode sounds.json")
+ exit(1)
+ }
+
+ return container
+}
+
+func processSingleSound(_ sound: SoundData, soundsDir: String) -> SoundData {
+ print("Analyzing: \(sound.fileName)")
+
+ guard let fileURL = findSoundFile(fileName: sound.fileName, in: soundsDir) else {
+ print(" ❌ File not found")
+ return sound
+ }
+
+ guard let analysis = analyzeLUFS(at: fileURL) else {
+ print(" ❌ Analysis failed")
+ return sound
+ }
+
+ printAnalysisResults(old: sound, new: analysis)
+
+ // Create updated sound with new values
+ let updatedSound = SoundData(
+ defaultOrder: sound.defaultOrder,
+ title: sound.title,
+ systemIconName: sound.systemIconName,
+ fileName: sound.fileName,
+ author: sound.author,
+ authorUrl: sound.authorUrl,
+ license: sound.license,
+ soundUrl: sound.soundUrl,
+ soundName: sound.soundName,
+ description: sound.description,
+ note: sound.note,
+ lufs: analysis.lufs,
+ normalizationFactor: analysis.normalizationFactor
+ )
+
+ print("")
+ return updatedSound
+}
+
+func findSoundFile(fileName: String, in directory: String) -> URL? {
+ let extensions = ["m4a", "wav", "mp3", "aiff"]
+
+ for ext in extensions {
+ let path = "\(directory)/\(fileName).\(ext)"
+ if FileManager.default.fileExists(atPath: path) {
+ return URL(fileURLWithPath: path)
+ }
+ }
+
+ return nil
+}
+
+func printAnalysisResults(old sound: SoundData, new analysis: AnalysisResult) {
+ let oldLUFS = sound.lufs ?? 0
+ let oldFactor = sound.normalizationFactor ?? 1
+
+ print(" Old: LUFS: \(oldLUFS), Factor: \(oldFactor)")
+ print(" New: LUFS: \(analysis.lufs), Factor: \(analysis.normalizationFactor)")
+
+ let difference = analysis.lufs - oldLUFS
+ if abs(difference) > 0.5 {
+ print(" ⚠️ Significant difference: \(difference) dB")
+ }
+}
+
+func saveUpdatedSounds(_ sounds: [SoundData], to outputPath: String) {
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+
+ let updatedContainer = SoundsContainer(sounds: sounds)
+
+ do {
+ let jsonData = try encoder.encode(updatedContainer)
+ try jsonData.write(to: URL(fileURLWithPath: outputPath))
+
+ print("\n✅ Updated sounds.json written to: sounds-updated.json")
+ print("To apply changes, run:")
+ print(" mv Blankie/Resources/sounds-updated.json Blankie/Resources/sounds.json")
+ } catch {
+ print("\n❌ Error writing updated JSON: \(error)")
+ }
+}
+
+main()
-
