From 72a36902aaa3b9fbff06a34331a78a558d417daa Mon Sep 17 00:00:00 2001 From: Anton Pauli <1565397+TUNER88@users.noreply.github.com> Date: Sun, 18 Oct 2026 22:38:20 +0200 Subject: [PATCH] docs: lead with dependency-free AudioToolbox usage; present the Swift package as optional --- README.md | 33 ++++++++----------- .../GettingStarted.md | 19 +++++++++-- .../SystemSoundsLibrary.md | 22 ++++++++++--- 3 files changed, 47 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 86f0ec2..2b5a4e3 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ A reference list of the system sounds built into iOS, plus a small demo app that - Run the demo project **on a real device** to hear all available system sounds. The iOS Simulator does not play system sounds. - See the [screenshot](#screenshot). -- API documentation for the `SystemSoundsLibrary` Swift package: +- The [usage](#usage) snippets call `AudioToolbox` directly. Copy and paste them; no dependency is needed. > [!NOTE] > Apple does not officially document these SystemSoundIDs or file names. The mappings below were collected on iOS 7 and **may differ, be missing, or be added on other iOS versions**. Always test on the iOS versions you support. @@ -12,10 +12,10 @@ A reference list of the system sounds built into iOS, plus a small demo app that ## Contents - [Usage](#usage) - - [Swift Package Manager](#swift-package-manager) - [Swift](#swift) - [SwiftUI](#swiftui) - [Objective-C](#objective-c) + - [Optional: Swift package](#swift-package-manager) - [List of SystemSoundIDs](#list-of-systemsoundids) - [List of all system audio files in iOS 7.0.2](#list-of-all-system-audio-files-in-ios-702) - [SystemSoundIDs added after iOS 7](#systemsoundids-added-after-ios-7) @@ -32,24 +32,7 @@ A reference list of the system sounds built into iOS, plus a small demo app that All examples use the `AudioToolbox` framework (System Sound Services). It is linked automatically when you import it in a modern Xcode project. -### Swift Package Manager - -The `SystemSoundsLibrary` package wraps these sounds in a typed Swift 6 API with availability information (iOS 15+, tvOS, visionOS, Mac Catalyst). Add it in Xcode with **File > Add Package Dependencies…**, or in `Package.swift`: - -```swift -dependencies: [ - .package(url: "https://github.com/TUNER88/iOSSystemSoundsLibrary", from: "2.0.0"), -], -``` - -```swift -import SystemSoundsLibrary - -SystemSoundPlayer.play(.smsReceived) // 1003 -await SystemSoundPlayer.playAndWait(.mailReceived) -``` - -See [`Examples/SoundBrowser`](Examples/SoundBrowser) for a SwiftUI app that browses and plays every sound. +The snippets below work as is. You don't need a third-party dependency to play system sounds. ### Swift @@ -113,6 +96,16 @@ if (AudioServicesCreateSystemSoundID((__bridge CFURLRef)fileURL, &soundID) == kA `AudioServicesPlaySystemSoundWithCompletion` requires iOS 9 or later. +### Swift Package Manager + +Optional, and not needed to play system sounds. If you'd like named constants with availability information instead of raw IDs, there's a small companion package ([documentation](https://tuner88.github.io/iOSSystemSoundsLibrary/documentation/systemsoundslibrary/)): + +```swift +.package(url: "https://github.com/TUNER88/iOSSystemSoundsLibrary", from: "2.0.0") + +SystemSoundPlayer.play(.smsReceived) // same as AudioServicesPlaySystemSound(1003) +``` + ## List of SystemSoundIDs Collected on iOS 7. Unofficial, and may differ on other iOS versions. diff --git a/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/GettingStarted.md b/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/GettingStarted.md index 46e8983..9444c26 100644 --- a/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/GettingStarted.md +++ b/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/GettingStarted.md @@ -1,8 +1,23 @@ # Getting started -Add the package and play your first system sound. +Play a system sound with AudioToolbox alone, or optionally add the package. -## Add the package +## You may not need this package + +To play a system sound, call System Sound Services directly. There's nothing to install: + +```swift +import AudioToolbox + +AudioServicesPlaySystemSound(1003) // SMSReceived +``` + +For the IDs and file names, see the tables in the +[README](https://github.com/TUNER88/iOSSystemSoundsLibrary#list-of-systemsoundids). The +package is optional. It adds named constants, availability annotations, async helpers and +``FileSound``, which disposes of its sound ID automatically. + +## Add the package (optional) In Xcode, choose **File > Add Package Dependencies…** and enter `https://github.com/TUNER88/iOSSystemSoundsLibrary`. Or add it to `Package.swift`: diff --git a/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/SystemSoundsLibrary.md b/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/SystemSoundsLibrary.md index a66c9ec..b217cb0 100644 --- a/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/SystemSoundsLibrary.md +++ b/Sources/SystemSoundsLibrary/SystemSoundsLibrary.docc/SystemSoundsLibrary.md @@ -1,17 +1,29 @@ # ``SystemSoundsLibrary`` -Play iOS system sounds by name, with availability information and Swift 6 concurrency safety. +An optional convenience layer over System Sound Services: named constants with availability information. ## Overview -`SystemSoundsLibrary` wraps System Sound Services (`AudioToolbox`) with a typed catalog of 418 known -system sounds. The catalog is generated from `data/sounds.json` in the -[iOSSystemSoundsLibrary](https://github.com/TUNER88/iOSSystemSoundsLibrary) repository. +You don't need this package to play system sounds. `AudioToolbox` ships with the SDK, and one +call is enough: + +```swift +import AudioToolbox + +AudioServicesPlaySystemSound(1003) // SMSReceived +``` + +The [iOSSystemSoundsLibrary](https://github.com/TUNER88/iOSSystemSoundsLibrary) README lists the +IDs and sound files, with copy-paste snippets for Swift, SwiftUI and Objective-C. + +If you'd rather use names than raw IDs, `SystemSoundsLibrary` wraps the same calls. It has a +typed catalog of 418 known sounds, generated from `data/sounds.json`, with `@available` +annotations for sounds added in newer iOS versions: ```swift import SystemSoundsLibrary -SystemSoundPlayer.play(.smsReceived) // 1003 +SystemSoundPlayer.play(.smsReceived) // same as AudioServicesPlaySystemSound(1003) await SystemSoundPlayer.playAndWait(.mailSentMailSent) if #available(iOS 17.0, *) {