macOS Play Alert Sound

From Free Pascal wiki
Revision as of 09:58, 8 May 2020 by Trev (talk | contribs) (Added AudioToolbox sound identifiers table and updated example code)

English (en)

macOSlogo.png

This article applies to macOS only.

See also: Multiplatform Programming Guide

Overview

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.

System Sound Services supported audio formats:

  • It only supports audio data formats linear PCM or IMA4.
  • It only supports audio file formats CAF, AIF, or WAV.

If these limitations on System Sound Services are an issue, check out the AVFoundation AVAudioPlayer which does not suffer from the limitations.

Alert Sound Identifiers

These are the AudioToolbox identifiers for alert sounds and alternatives to sounds, for use with the AudioServicesPlayAlertSound:

Identifier Description
kSystemSoundID_Vibrate On the iPhone, use this constant with the AudioServicesPlayAlertSound function to invoke a brief vibration. On the iPod touch, does nothing.
kSystemSoundID_UserPreferredAlert On the desktop, use this constant with the AudioServicesPlayAlertSound function to play the alert specified in the Sound preference pane.
kSystemSoundID_FlashScreen On the desktop, use this constant with the AudioServicesPlayAlertSound function to display a flash of light on the screen.
kUserPreferredAlert Deprecated. Use kSystemSoundID_UserPreferredAlert instead.

Example code

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.

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 :-)

Alternatively, you can use the sound identifier variables listed in the section above.

unit unit1;

{$mode objfpc}{$H+}
{$linkframework AudioToolbox}

interface

uses
  Forms,
  Menus;

type

  { TForm1 }

  TForm1 = class(TForm)
    MainMenu1: TMainMenu;
    MenuItem1: TMenuItem;
    procedure MenuItem1PlaySoundClick(Sender: TObject);
    MenuItem2: TMenuItem;
    procedure MenuItem2PlaySoundClick(Sender: TObject);

  private

  public

  end;

var
  Form1: TForm1;

implementation

{$R *.lfm}

{ TForm1 }

// Sound procedure declaration 
Procedure AudioServicesPlayAlertSound (inSystemSoundID: UInt32)
   external name '_AudioServicesPlayAlertSound';

// Menu item1 OnClick Event
procedure TForm1.MenuItem1PlaySoundClick(Sender: TObject);
begin
  AudioServicesPlayAlertSound(2);  // Use the appropriate value for the sound you want
end;

// Menu item2 OnClick Event
procedure TForm1.MenuItem2PlaySoundClick(Sender: TObject);
begin
  AudioServicesPlayAlertSound(kSystemSoundID_UserPreferredAlert);  // Use the user's preferred alert sound
end;

end.


Playing an alert sound from a file

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 number assigned to the sound.


unit Unit1;


{$mode objfpc}{$H+}
{$linkframework AudioToolbox}

interface


uses
 Classes,
 SysUtils,
 Forms,
 Controls,
 StdCtrls,
 Dialogs,
 MacOSAll;

type

 TSystemSoundID = UInt32;
 pSystemSoundID = ^TSystemSoundID;

 { TForm1 }

 TForm1 = class(TForm)
   Button1: TButton;
   procedure Button1Click(Sender: TObject);
 private

 public

 end;


var
 Form1: TForm1;


implementation


{$R *.lfm}


{ TForm1 }

// Sound procedure and function declarations
procedure AudioServicesPlayAlertSound (inSystemSoundID: TSystemSoundID); external name '_AudioServicesPlayAlertSound';
function AudioServicesCreateSystemSoundID(inFileURL: CFURLRef; outSystemSoundID: pSystemSoundID):OSStatus; external name '_AudioServicesCreateSystemSoundID';

procedure TForm1.Button1Click(Sender: TObject);
var
   newSoundID:TSystemSoundID;
   filePathURL: CFURLRef;
   filePathCFStringRef: CFStringRef;
   filePathStr: String;
   status: Integer = -1;
begin
 // Play sound from file
 filePathStr := '/usr/local/share/fpcsrc/fpc-3.0.4/packages/libndsfpc/examples/audio/maxmod/basic_sound/audio/Ambulance.wav';
 filePathCFStringRef := CFStringCreateWithPascalString(kCFAllocatorDefault, filePathStr, CFStringGetSystemEncoding);
 filePathURL := CFURLCreateWithFileSystemPath(kCFAllocatorDefault, filePathCFStringRef, kCFURLPOSIXPathStyle, false);

 status := AudioServicesCreateSystemSoundID(filePathURL, @newSoundID);

 if(status = kAudioServicesNoError) then
   begin
      Button1.Caption := IntToStr(newSoundID);
      AudioServicesPlayAlertSound(newSoundID);
   end
 else
   ShowMessage('Error in AudioServicesCreateSystemSoundID()');
end;

end.

See also

External links