Sound Sway

Sound Sway is an iPhone app for controlling system volume with tilt, touch, Shortcuts, and an optional Air Toss boost. It is designed for fast one-handed volume changes without depending only on hardware buttons or Control Center.

The app combines a direct volume dial, intentional tilt activation, configurable thresholds, safety guards, App Intents, and lightweight product analytics. It works within normal iOS app constraints, so active tilt control is available while the app is open and armed.

Overview

• Tilt toward the user to raise volume and away to lower it
• Start and stop tilt sessions with a deliberate double-shake flow
• Use a circular dial and manual controls when touch is faster than motion
• Recenter the neutral baseline to match how the phone is naturally held
• Configure trigger angles, tilt sensitivity, and auto-stop timing
• Reduce accidental input with Pocket Safe Mode and Walking Guard
• Launch quickly through App Shortcuts, Back Tap, or Action Button
• Review local usage activity and optionally enable troubleshooting logs
• Turn Air Toss on or off, track last and record toss height across relaunches, and watch a live toss animation while the phone is airborne

How It Works

1. Open Sound Sway directly or through a Shortcut, Action Button shortcut, or Back Tap shortcut.
2. Arm tilt control from the main screen.
3. Double-shake to begin a tilt session.
4. Tilt toward yourself to increase volume or away to decrease it.
5. Volume changes begin only after the configured trigger thresholds are crossed.
6. Use the central dial, Up, Down, Mute, 50%, or 80% when manual control is easier.
7. If Air Toss is enabled, a detected toss temporarily ignores tilt, uses hang time to calculate a capped volume boost, and animates the phone rising through the Air Toss card while the throw is in progress.
8. Recenter the baseline whenever your natural hold angle changes.

Important: Sound Sway does not provide a background system-wide gesture layer. Its tilt behavior is intended for active use while the app is on screen.

Features

Volume Control

• Circular dial for direct volume setting
• Manual Up and Down controls
• Quick presets for mute, 50%, and 80%
• Bridge readiness feedback while the hidden system volume bridge is attaching

Tilt Control

• Double-shake start and stop interaction
• Separate up and down trigger angles
• Learn-by-moving mode for teaching trigger angles from live device motion
• Recenter baseline to reduce false activation
• Adjustable tilt sensitivity
• Adjustable tilt auto-stop interval
• Optional Air Toss mode with airborne tilt suppression and hang-time-based boost
• Animated Air Toss flight feedback while the throw is in progress
• Last and record toss-height stats that persist across relaunches
• New-record celebration feedback when a toss beats your best height

Safety And Stability

• Pocket Safe Mode blocks tilt while the proximity sensor is covered
• Walking Guard pauses tilt when motion resembles walking, running, or cycling
• Auto-stop ends an active tilt session after inactivity
• Continuous refresh keeps the UI aligned with external system-volume changes

Integrations

• App Shortcuts for Start Sound Sway, Angle +, Angle -, and Recenter
• Additional intents for mute, tilt armed state, and trigger changes
• Launch-friendly setup for Back Tap and Action Button flows

Widget note: the widget target is still present in the repository, but widget functionality is currently not maintained and should be treated as incomplete or unreliable until it is rebuilt.

Observability

• Local app-usage activity logging for product-level interaction events
• Optional troubleshooting logs for technical investigation
• Share flow for exporting the usage log from the troubleshooting sheet

User Experience Flow

Typical Tilt Session

1. Launch the app.
2. Turn tilt control on if needed.
3. Double-shake to arm an active tilt session.
4. Tilt past the configured trigger angle.
5. Let auto-stop end the session, or double-shake again to stop.

Manual Control Flow

1. Open the app.
2. Adjust with the dial or use Up, Down, Mute, 50%, or 80%.
3. Recenter if tilt feels offset from your natural hold.

Project Structure

Sound Sway.xcodeproj/                Xcode project
SoundSway/                           Main iOS app target
  App/                               App lifecycle, model, logging
  Features/Main/                     Main interface and volume bridge UI
  Intents/                           App Intents and Shortcuts integration
  Services/                          Tilt, safety, and volume services
  Shared/                            App-group shared state for app and widget
SoundSwayWidget/                     Widget extension
SoundSwayTests/                      Unit tests and test support

Architecture

Main App

• SoundSway/App/AppModel.swift Central app state, persistence wiring, volume actions, safety state, activity logging, and widget notifications.
• SoundSway/Features/Main/ContentView.swift Main glass-style UI, volume dial, manual controls, theme picker, and setup or troubleshooting sheets.

Services

• TiltActivationEngine Handles double-shake activation and tilt session state.
• TiltVolumeController Converts device motion into up or down tilt intent and detects short toss flights for Air Toss boosts.
• EnvironmentSafetyMonitor Watches for safety conditions such as pocket coverage and motion-guard states.
• VolumeManager Reads and writes system volume through the supported bridge.
• AppServices Provides service composition for the app target.

Integrations

• SoundSwayShortcutsProvider Declares the user-facing App Shortcuts.
• LiveActivityControlIntents and related intents Provide automation and external action hooks.
• SoundSwayHomeWidget Legacy widget implementation kept in the repository for future rebuild work, but not currently considered a stable supported feature.

Requirements

• Xcode 17 or newer
• iOS 17.0 deployment target
• Apple signing configured in Xcode
• A real iPhone for meaningful tilt, motion, proximity, and Action Button validation

Build And Run

1. Open Sound Sway.xcodeproj in Xcode.
2. Set your signing team on the app target. Configure the widget target only if you are actively rebuilding or debugging it.
3. Build and run on a device.
4. On first launch, recenter the baseline so the app matches the user’s natural hold angle.

Example CLI build:

xcodebuild -project 'Sound Sway.xcodeproj' -scheme 'Sound Sway' -destination 'generic/platform=iOS' build

Setup Options

Shortcuts

Create a Shortcut using Open App -> Sound Sway, or use the built-in App Shortcuts:

• Start Sound Sway
• Angle +
• Angle -
• Recenter

Back Tap

1. Create a Shortcut that opens Sound Sway.
2. Assign it in Settings -> Accessibility -> Touch -> Back Tap.

Action Button

On supported devices, assign a Shortcut that opens Sound Sway from Settings -> Action Button.

Widget

The widget target remains in the project, but widget behavior is currently outdated and not reliable enough to recommend as part of normal use.

Logging And Diagnostics

App Usage Activity

• Stored locally
• Intended for product understanding rather than deep debugging
• Captures meaningful actions such as app launch, arming, recentering, manual volume actions, safety blocks, theme changes, and sheet opens

Troubleshooting Logs

• Intended only for technical debugging
• Capture more detailed internal behavior around bridge, tilt, trigger, and safety flows
• Should remain off during normal use unless active investigation is needed

Testing

The SoundSwayTests target currently covers:

• First-launch defaults
• Manual volume buttons, presets, and mute restore behavior
• External system-volume refresh behavior
• Tilt activation state transitions
• Blocked tilt-state feedback
• Tilt controller behavior

Privacy And Security

• App-usage logging is local-first and intentionally lightweight
• Troubleshooting logs should be enabled only when needed
• Avoid collecting personal content, credentials, or unrelated device data
• Do not commit secrets, provisioning material, or local diagnostic artifacts
• Shared app and widget state uses an app group and should stay narrowly scoped, especially while the widget implementation is being reworked

Sound Sway should continue to be reviewed over time for privacy, safety, and stability improvements as the feature set grows.

Current Priorities

• Keep tilt behavior predictable and easy to recover from
• Preserve a polished and responsive UI
• Improve observability without over-collecting user data
• Keep the app model and services aligned as features evolve
• Rebuild or remove the legacy widget path so the documentation and shipped behavior match