Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 13 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@ 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: <https://tuner88.github.io/iOSSystemSoundsLibrary/documentation/systemsoundslibrary/>
- 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.

## 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)
Expand All @@ -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

Expand Down Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
@@ -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`:
Expand Down
Original file line number Diff line number Diff line change
@@ -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, *) {
Expand Down
Loading