macOS Play Alert Sound: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: macOS Play Alert Sound

New		Line
1	+	(macOS only)
2	+
3	+	## Overview
4	+
5	+	The Apple macOS operating system has many possible alert sounds which you can play to alert your user to various situation that need their attention. You can use System Sound Services to play short (30 seconds or shorter) sounds. The interface does not provide level, positioning, looping, or timing control, and does not support simultaneous playback: You can play only one sound at a time and the sound only plays once. You can, however, use System Sound Services to provide audible alerts.
6	+
7	+	System Sound Services supported audio formats:
8	+
9	+	- It only supports audio data formats linear PCM or IMA4.
10	+	- It only supports audio file formats CAF, AIF, or WAV.
11	+
12	+	If these limitations on System Sound Services are an issue, check out the AVFoundation [[macOS Audio Player\|AVAudioPlayer]] which does not suffer from the limitations.
13	+
14	+	## Alert Sound Identifiers
15	+
16	+	These are the AudioToolbox identifiers for System Sound Services alert sounds and alternatives to sounds, for use with the AudioServicesPlayAlertSound:
17	+
18	+	\| Identifier \| Description \|
19	+	\|----\|----\|
20	+	\| kSystemSoundID_Vibrate \| On the iPhone, use this constant with the AudioServicesPlayAlertSound function to invoke a brief vibration. On the iPod touch, does nothing. \|
21	+	\| kSystemSoundID_UserPreferredAlert \| On the desktop, use this constant with the AudioServicesPlayAlertSound function to play the alert specified in the Sound preference pane. \|
22	+	\| kSystemSoundID_FlashScreen \| On the desktop, use this constant with the AudioServicesPlayAlertSound function to display a flash of light on the screen. \|
23	+	\| kUserPreferredAlert \| Deprecated. Use kSystemSoundID_UserPreferredAlert instead. \|
24	+
25	+	When a user has configured System Preferences to flash the screen for alerts, or if sound cannot be rendered, calling AudioServicesPlayAlertSound will result in the screen flashing. In macOS, pass the constant kSystemSoundID_UserPreferredAlert to play the alert sound selected by the user in System Preferences.
26	+
27	+	## Result codes
28	+
29	+	This table lists the result codes defined for System Sound Services:
30	+
31	+	\| Constant \| Value \| Description \|
32	+	\|----\|----\|----\|
33	+	\| kAudioServicesNoError \| 0 \| No error has occurred \|
34	+	\| kAudioServicesUnsupportedPropertyError \| 'pty?' \| The property is not supported \|
35	+	\| kAudioServicesBadPropertySizeError \| '!siz' \| The size of the property data was not correct \|
36	+	\| kAudioServicesBadSpecifierSizeError \| '!spc' \| The size of the specifier data was not correct \|
37	+	\| kAudioServicesSystemSoundUnspecifiedError \| -1500 \| An unspecified error has occurred \|
38	+	\| kAudioServicesSystemSoundClientTimedOutError \| -1501 \| System sound client message timed out \|
39	+
40	+	## Example code
41	+
42	+	The example application code below shows how to play those alert sounds. In this example the alert sound is being played by choosing a menu item which is just for the purposes of the demonstration.
43	+
44	+	Note that the choice of 2 for the alert sound to play in this example is purely arbitrary. You should choose the number for the appropriate sound you want to play. Sound number 4096 is particularly interesting for deaf users. Try it :-)
45	+
46	+	Alternatively, you can use the sound identifier variables listed in the section above.
47	+
48	+	``` pascal
49	+	unit unit1;
50	+
51	+	{$mode objfpc}{$H+}
52	+	{$linkframework AudioToolbox}
53	+
54	+	interface
55	+
56	+	uses
57	+	Forms,
58	+	Menus;
59	+
60	+	type
61	+
62	+	{ TForm1 }
63	+
64	+	TForm1 = class(TForm)
65	+	MainMenu1: TMainMenu;
66	+	MenuItem1: TMenuItem;
67	+	procedure MenuItem1PlaySoundClick(Sender: TObject);
68	+	MenuItem2: TMenuItem;
69	+	procedure MenuItem2PlaySoundClick(Sender: TObject);
70	+
71	+	private
72	+
73	+	public
74	+
75	+	end;
76	+
77	+	var
78	+	Form1: TForm1;
79	+
80	+	implementation
81	+
82	+	{$R *.lfm}
83	+
84	+	{ TForm1 }
85	+
86	+	// Sound procedure declaration
87	+	Procedure AudioServicesPlayAlertSound (inSystemSoundID: UInt32)
88	+	external name '_AudioServicesPlayAlertSound';
89	+
90	+	// Menu item1 OnClick Event
91	+	procedure TForm1.MenuItem1PlaySoundClick(Sender: TObject);
92	+	begin
93	+	AudioServicesPlayAlertSound(2); // Use the appropriate value for the sound you want
94	+	end;
95	+
96	+	// Menu item2 OnClick Event
97	+	procedure TForm1.MenuItem2PlaySoundClick(Sender: TObject);
98	+	begin
99	+	AudioServicesPlayAlertSound(kSystemSoundID_UserPreferredAlert); // Use the user's preferred alert sound
100	+	end;
101	+
102	+	end.
103	+	```
104	+
105	+	## Playing an alert sound from a file
106	+
107	+	Not only can you play the existing operating system alert sounds, you can also play your own .wav sound files. The example application below demonstrates this. The Button1 OnClick event handler plays your sound from the specified file and updates the button caption with the SoundID assigned to the sound.
108	+
109	+	``` pascal
110	+	unit Unit1;
111	+
112	+	{$mode objfpc}{$H+}
113	+	{$modeswitch objectivec1}
114	+	{$linkframework AudioToolbox}
115	+
116	+	interface
117	+
118	+	{$DEFINE DEBUG} // Comment if console log messages may required
119	+
120	+	uses
121	+	Classes,
122	+	SysUtils,
123	+	Forms,
124	+	Controls,
125	+	StdCtrls,
126	+	Dialogs,
127	+	{$IFDEF DEBUG}
128	+	CocoaAll,
129	+	{$ENDIF}
130	+	MacOSAll;
131	+
132	+	type
133	+
134	+	TSystemSoundID = UInt32;
135	+	pSystemSoundID = ^TSystemSoundID;
136	+
137	+	{ TForm1 }
138	+
139	+	TForm1 = class(TForm)
140	+	Button1: TButton;
141	+	procedure Button1Click(Sender: TObject);
142	+	private
143	+
144	+	public
145	+
146	+	end;
147	+
148	+	var
149	+	Form1: TForm1;
150	+
151	+	implementation
152	+
153	+	{$R *.lfm}
154	+
155	+	// Completion handler: Executed when the sound file finishes playing
156	+	procedure myCompletionHandler(SoundID: SystemSoundID; inClientData: CFStringRef);
157	+	begin
158	+	AudioServicesDisposeSystemSoundID(SoundID); // Dispose of a system sound object and associated resources
159	+	{$IFDEF DEBUG}
160	+	NSLog(NSStr('Completion handler called'));
161	+	{$ENDIF}
162	+	end;
163	+
164	+	// System Sound Services procedure and function declarations
165	+	procedure AudioServicesPlayAlertSound (inSystemSoundID: TSystemSoundID);
166	+	external name '_AudioServicesPlayAlertSound';
167	+	function AudioServicesCreateSystemSoundID(inFileURL: CFURLRef; outSystemSoundID: pSystemSoundID): OSStatus;
168	+	external name '_AudioServicesCreateSystemSoundID';
169	+	function AudioServicesAddSystemSoundCompletion (inSystemSoundID: TSystemSoundID; inRunLoop: CFRunLoopRef; inRunLoopMode: CFStringRef; inCompletionRoutine: Pointer; inClientData: CFURLRef): OSStatus; cdecl;
170	+	external name 'AudioServicesAddSystemSoundCompletion';
171	+	function AudioServicesDisposeSystemSoundID(inSystemSoundID: TSystemSoundID): OSStatus; cdecl;
172	+	external name '_AudioServicesDisposeSystemSoundID';
173	+
174	+	{ TForm1 }
175	+
176	+	procedure TForm1.Button1Click(Sender: TObject);
177	+	var
178	+	newSoundID: TSystemSoundID;
179	+	filePathURL: CFURLRef;
180	+	filePathCFStringRef: CFStringRef;
181	+	filePathStr: String;
182	+	status: Integer = -1;
183	+	begin
184	+	// Sound file to play
185	+	filePathStr := '/usr/local/share/fpcsrc/fpc-3.0.4/packages/libndsfpc/examples/audio/maxmod/basic_sound/audio/Ambulance.wav';
186	+	filePathCFStringRef := CFStringCreateWithPascalString(kCFAllocatorDefault, filePathStr, CFStringGetSystemEncoding);
187	+	filePathURL := CFURLCreateWithFileSystemPath(kCFAllocatorDefault, filePathCFStringRef, kCFURLPOSIXPathStyle, false);
188	+
189	+	// Create a new system sound object
190	+	status := AudioServicesCreateSystemSoundID(filePathURL, @newSoundID);
191	+	if(status = kAudioServicesNoError) then
192	+	begin
193	+	Button1.Caption := IntToStr(newSoundID);
194	+
195	+	// Register a callback function, invoked when specified system sound finishes playing
196	+	status := AudioServicesAddSystemSoundCompletion(newSoundID, Nil, Nil, @myCompletionHandler, Nil);
197	+	if(status <> kAudioServicesNoError) then
198	+	ShowMessage('Error in AudioServicesAddSystemSoundCompletion() : ' + IntToStr(status));
199	+
200	+	// Play sound
201	+	AudioServicesPlayAlertSound(newSoundID);
202	+	end
203	+	else
204	+	ShowMessage('Error in AudioServicesCreateSystemSoundID() : ' + IntToStr(status));
205	+	end;
206	+
207	+	end.
208	+	```
209	+
210	+	In the code above we are disposing of the system sound object and its associated resources in the completion handler procedure. You will not want to do this if you wish to replay the sound using it SoundID at a later time in the application (eg in a game).
211	+
212	+	## See also
213	+
214	+	- [[macOS Audio Player\|AVAudioPlayer]]
215	+	- [[macOS NSSound]]
216	+	- [[macOS Programming Tips\|NSBeep]]
217	+	- [[macOS Sound Utilities]]
218	+	- [[Multimedia Programming]]
219	+
220	+	## External links
221	+
222	+	- [Apple: Working with Audio](https://developer.apple.com/audio/)
223	+	- [Apple: System Sound Services](https://developer.apple.com/documentation/audiotoolbox/system_sound_services)
224	+
225	+	---
226	+	From the Free Pascal wiki, page "macOS Play Alert Sound", as it stood on 2020-06-20 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
227	+	Category: Audio
228	+	Category: Code Snippets
229	+	Category: Multimedia
230	+	Category: macOS

Back to history