HERE iOS SDK Developer's Guide

NMAAudioManager

Class Summary

class NMAAudioManager

Derived from: NSObject

Manages the playback of audio output from files or TTS.

Include: NMAKit.framework/headers/NMAAudioManager.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMAAudioManager

[For complete information, see the section Class Details]

Public Property Summary

Table 1. Public Properties
Public Properties

[readable, assign] NMAAudioRoute   audioRoute

[readable, writable, assign] NSTimeInterval  audioRouteLatencyCompensation

[readable, writable, assign] BOOL  captureHardwareVolumeKeys

Controls whether the SDK will always capture the hardware volume keys

[readable, writable, weak] id< NMAAudioManagerDelegate delegate

The delegate of the NMAAudioManager, implementing the NMAAudioPlayerDelegate protocol

[readable, writable, assign] BOOL  managesAudioSession

Controls whether the NMAAudioManager manages the application's audio session

[readable, writable, assign] float  volume

The playback volume clamped to the range 0 to 1

Instance Method Summary

Table 2. Instance Methods
Instance Method Summary

-(void) clearQueue

Removes all output from the audio queue

-(void) playOutput:( NMAAudioOutput *) output

Requests playback of an output segment

-(BOOL) setAudioRoute:( NMAAudioRoute ) audioRoute

Force audio output to a specific audio route

-(void) skipCurrentOutput

Skips the output at the front of the queue

-(void) stopOutputAndClearQueue

Stops playing the current output immediately and clears any queued output.

Class Method Summary

Table 3. Class Methods
Class Methods

+( NMAAudioManager *) sharedAudioManager

Accesses the NMAAudioManager singleton object

Class Details

Manages the playback of audio output from files or TTS.

The NMAAudioManager singleton is used to play audio output segments. It is also responsible for managing the app's AVAudioSession to properly handle audio behaviour in all circumstances. This includes setting the audio session category, and activating and deactivating the session as needed to play output and combine appropriately with other audio sources (such as background music).

Currently, only serial playback is supported. The audio manager maintains a queue of audio output, the elements of which are played in FIFO order.

Note:

Must only be called on the main thread.

Public Property Details

[readable, assign] NMAAudioRoute  audioRoute

The current audio output route

[readable, writable, assign] NSTimeInterval audioRouteLatencyCompensation

The expected hardware latency when establishing the audio output route

This property is provided to prevent the beginning of audio outputs being clipped due audio routing latency hardware issues. For example, when establishing a bluetooth connection to a car radio.

If this property is > 0 and an audio route has not yet been established yet then an NMAAudioFileOutput of silence equal to the value of this property will be inserted into the audio output queue prior to playing pending audio outputs.

Defaults to 0 (no latency). Negative values are ignored.

Note:

The value used should be as low as possible since it effectively delays the playback of audio outputs, including navigation voice feedback.

[readable, writable, assign] BOOL captureHardwareVolumeKeys

Controls whether the SDK will always capture the hardware volume keys.

When set to YES, and the app is in the foreground, the hardware volume keys will control the "App" volume maintained by the the OS. The "App" volume is not the same as the volume controlled by the [ NMAAudioManager volume] property.

However, if [ NMAAudioManager audioRoute] is NMAAudioRouteDeviceSpeaker and other apps on the device are currently playing audio or if [ NMAAudioManager audioRoute] is NMAAudioRouteBluetoothHFP then the hardware volume keys will not be captured.

When set to NO the hardware volume keys will control the volume of the audio source deemed most appropriate by the OS. Most commonly the Phone Ringer or the Music Player.

Defaults to NO.

This property is ignored if the [ NMAAudioManager manageAudioSession] property is set to NO.

Note:

Hardware volume keys are always captured during an NMANavigationManager navigation or tracking session (i.e. between calls to start and stop navigation).

[readable, writable, weak] id< NMAAudioManagerDelegatedelegate

The delegate of the NMAAudioManager, implementing the NMAAudioPlayerDelegate protocol.

See also:

NMAAudioManagerDelegate

[readable, writable, assign] BOOL managesAudioSession

Controls whether the NMAAudioManager manages the application's audio session.

If managesAudioSession is YES, the NMAAudioManager will change the type of the audio session and activate and deactivate the session as necessary to play SDK audio output.

If managesAudioSession is NO, it is up to the application to properly configure the audio session. In this case, the NMAAudioManager will notify its delegate when SDK audio is available via the audioManager:shouldPlayOutput method of NMAAudioManagerDelegate.

Typically, the audio session management policy should be set when the application is first launched or before the first usage of SDK audio output. It is not recommended to change this property while audio playback features are in use.

Note:

The default value is YES.

See also:

NMAAudioManagerDelegate

[readable, writable, assign] float volume

The playback volume clamped to the range 0 to 1.0.

This volume will be applied to all NMAAudioOutput objects played by the audio manager and may be used to adjust volume level relative to other audio sources on the device (e.g. the music player) or within the application.

Changes in volume will be immediately applied to the currently playing NMAAudioOutput object, but note that changes to the volume of an NMATTSAudioOutput object will not be audible after playback starts. This is a limitation of the underlying iOS AVSpeechUtterance class.

Defaults to 1.0 (full volume).

Note:

This volume value is applied as a multiplier to the "App" volume maintained by the OS. The latter can only be controlled by the hardware volume keys or the iOS MPVolumeView UIControl.

Instance Method Details

-(void) clearQueue

Removes all output from the audio queue.

Note:

If audio is currently playing, it will be allowed to finish.

-(void) playOutput:( NMAAudioOutput *) output

Requests playback of an output segment.

Output segments are played in the order in which they are received. If no audio is currently playing when this method is called, the provided output will be played immediately. Otherwise, the output will be added to the end of the queue.

Note:

This method is used to add new output to the audio playback queue. It should not be called for output already in the queue; for example, output received from the audioManager:shouldPlayOutput: method of NMAAudioManagerDelegate.

-(BOOL) setAudioRoute:( NMAAudioRoute ) audioRoute

Force audio output to a specific audio route.

The new audio route will be applied on the next NMAAudioOutput playback. If the route is not available at that time (e.g. BT HFP device never connected or disconnected) then the route will revert to NMAAudioRouteDefault before playback and an NMAAudioRouteDidChangeNotification notification will be posted.

Note:

Calling this method does not cause a NMAAudioRouteDidChangeNotification notification to be posted.

Parameters:

  • audioRoute

    NMAAudioRoute to use

Returns:

YES if the route was set, NO otherwise (e.g. if route is not supported on iOS7)

-(void) skipCurrentOutput

Skips the output at the front of the queue.

If the current output has already started playing, it will be interrupted. The next output item in the queue will be played.

-(void) stopOutputAndClearQueue

Stops playing the current output immediately and clears any queued output.

Class Method Details

+( NMAAudioManager *) sharedAudioManager

Accesses the NMAAudioManager singleton object.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.