class DJISpeaker
@interface DJISpeaker : DJIBaseComponent
Description:
The class represents the speaker accessory on the aircraft. Used transmit audio files and control the speaker.
Class Members:
property fileListState
@property (nonatomic , readonly ) DJIMediaFileListState fileListState
Description:
Current file list state of the speaker.
See Also:
DJIMediaFileListState
Data Transmission State
property
property dataTransmissionState
@property (nonatomic , readonly ) DJISpeakerDataTransmissionState dataTransmissionState
Description:
The data transmission state of the speaker.
See Also:
DJISpeakerDataTransmissionState
method setVolume:withCompletion
- (void )setVolume:(NSUInteger )volume withCompletion:(DJICompletionBlock)completion
Description:
Sets the volume to play audio. The valid range is [0, 100]. 100 means loudest.
NSUInteger volume Volume value to set. DJICompletionBlock completion Completion block to receive the result.
method setPlayMode:withCompletion
- (void )setPlayMode:(DJISpeakerPlayMode)playMode withCompletion:(DJICompletionBlock)completion
Description:
Sets the play mode of the speaker to control the behavior after finishing playing a file.
method startTransmissionWithInfo:startBlock:onProgress:finish:failure
- (void )startTransmissionWithInfo:(DJIAudioFileInfo *)info
startBlock:(DJISpeakerTransmissionStartBlock)startBlock
onProgress:(DJISpeakerTransmissionOnProgressBlock)progressBlock
finish:(DJISpeakerTransmissionFinishBlock)finishBlock
failure:(DJISpeakerTransmissionFailureBlock)failureBlock
Description:
Starts to send a complete audio file to the aircraft, which can be played by the speaker. A transmission session can only be started when the transmission state is in DJISpeakerDataTransmissionStateIdle
. If the transmission is started successfully, the state will change to DJISpeakerDataTransmissionStateReadyToTransmit
. Then call paceData
to send data to SDK. Call markEOF
when all data has been sent to SDK. SDK will maintain a buffer to hold all the data and transmit it to the aircraft. For M2E Speaker, the audio file to transmit should fulfill the following configurations: - The speaker only receives raw PCM(Pulse-code modulation) data of an audio file, if the audio file is compressed, PCM extraction is needed before the transmission. - The audio channel is mono. - The audio sample rate is 44,100 Hz. - The PCM (Pulse-code modulation) sample depth is 16 bit per sample. - The audio file is stored in the aircraft instead of the speaker.
method paceData
- (BOOL )paceData:(NSData *)data
Description:
Sends raw PCM data of the audio file to SDK internal logic. The raw PCM data is the AudioBufferList that will be used to contain the rendered or provided audio data. For Mavic 2 Enterprise, the transmission rate is limited to 80kB/s by sdk. Therefore, SDK will cache the paced data to a local file when the rate of pacing data is over 80kB/s. The paced data will be appended to the local file. Call markEOF
when all data of the data has been paced to SDK.
NSData * data Raw PCM data stream in bytes.
Return:
BOOL YES
if data is paced successfully. Otherwise, pacing data is not in the current state or the data size is illegal.
method markEOF
Description:
Marks EOF (end-of-file). It is used to inform SDK that all data of the file has been paced. SDK will continue to transmit data to the aircraft. The state will change to DJISpeakerDataTransmissionStateIdle
when all data is transmitted. After calling this method, paceData
is invalid until a new transmission session starts. If no data is paced before calling this method, the transmission session will end immediately.
Return:
NSError * The occurred error if any.
Cancel Transmission
method
method cancelTransmission
- (void )cancelTransmission
Description:
This will entirely stop the data transfer process and of course clean the transfer thread pool.
method play:withCompletion
- (void )play:(NSUInteger )fileIndex withCompletion:(DJICompletionBlock)completion
Description:
Starts to play the audio file with the specific index.
NSUInteger fileIndex The file index of the AudioMediaFile
to play. DJICompletionBlock completion Completion block to receive the result.
method stopAudioPlayWithCompletion
- (void )stopAudioPlayWithCompletion:(DJICompletionBlock)completion
Description:
Stops the speaker from playing audio. The method is only valid when the playing state is DJISpeakerPlayingStatePlaying
.
method rename:index:withCompletion
- (void )rename:(NSString *)fileName index:(NSUInteger )index withCompletion:(DJICompletionBlock)completion
Description:
Renames the audio file with the specific index. If the operation is started successfully, FileListState will become DJIMediaFileListStateRenaming
.
NSUInteger index The index of the audio file to rename. NSString * fileName The new file name of the audio file. The file name should not exceed 128 characters. DJICompletionBlock completion Completion block to receive the result.
Get File List Snapshot
method
method fileListSnapshot
- (NSArray <DJIAudioMediaFile*> *)fileListSnapshot
Description:
Returns a copy of the current audio file list from the storage. Returns null
if fileListState
is reset.
Return:
method deleteFiles:withCompletion
- (void )deleteFiles:(NSArray <NSNumber *> *)fileIndices withCompletion:(void (^_Nullable)(NSArray <NSNumber *> *_Nonnull failedFiles, NSError *_Nullable error))completion
Description:
Deletes audio files in the aircraft. If the operation is started successfully, fileListState
will become DJIMediaFileListStateDeleting
. If there is error or "failedFiles" is not empty, fileListState
will become DJIMediaFileListStateReset
.
NSArray<NSNumber*> * fileIndices A list of AudioMediaFile's index. NSArray<NSNumber*> *_Nonnull failedFiles Delete failed files. NSError *_Nullable error Error deleting the files. void (^_Nullable)(NSArray<NSNumber*> *_Nonnull failedFiles, NSError *_Nullable error) completion Completion block to receive the result.
Add Speaker State Listener
method
method addSpeakerStateListener:withQueue:andBlock
- (void )addSpeakerStateListener:(id )listener
withQueue:(nullable dispatch_queue_t )queue
andBlock:(DJISpeakerStateBlock)block
Description:
Adds listener to receive the latest state of the speaker.
id listener The listener to receive the state. SDK will add reference count of the listener. Call removeSpeakerStateListener
to release the resource. nullable dispatch_queue_t queue The queue to execute the block. Pass NULL to use the default queue. DJISpeakerStateBlock block Block that will be executed when the state is updated.
Remove Speaker State Listener
method
method removeSpeakerStateListener
- (void )removeSpeakerStateListener:(id )listener
Description:
Removes the listener of the speaker state.
id listener The listener to remove.
Add File List State Listener
method
method addFileListStateListener:withQueue:andBlock
- (void )addFileListStateListener:(id )listener
withQueue:(nullable dispatch_queue_t )queue
andBlock:(DJISpeakerFileListStateBlock)block
Description:
Adds listener to receive the latest file list state of the speaker.
id listener The listener to receive the state. SDK will add reference count of the listener. Call removeFileListStateListener
to release the resource. nullable dispatch_queue_t queue The queue to execute the block. Pass 'NULL' to use the default queue. DJISpeakerFileListStateBlock block Block that will be executed when the state is updated.
Remove File List State Listener
method
method removeFileListStateListener
- (void )removeFileListStateListener:(id )listener
Description:
Removes the listener of the speaker file list state.
id listener Listener to be removed.
typedef block DJISpeakerTransmissionStartBlock
typedef void (^DJISpeakerTransmissionStartBlock) ()
Description:
Called when the transmission starts and the aircraft is ready to receive data of the audio file from the mobile device.
typedef block DJISpeakerTransmissionOnProgressBlock
typedef void (^DJISpeakerTransmissionOnProgressBlock) (NSInteger dataSize)
Description:
Called to update the transmission progress. The progress is updated when a chunk of data is received successfully by the aircraft.
NSInteger dataSize The accumulated data size of the audio file received by the aircraft.
typedef block DJISpeakerTransmissionFinishBlock
typedef void (^DJISpeakerTransmissionFinishBlock) (NSInteger index)
Description:
Called when the transmission finishes successfully.
NSInteger index The index assigned by the aircraft for the new audio file.
typedef block DJISpeakerTransmissionFailureBlock
typedef void (^DJISpeakerTransmissionFailureBlock) (NSError *error)
Description:
Called when the transmission is interrupted by an error.
NSError * error The possible error during the transmission.
typedef block DJISpeakerFileListStateBlock
typedef void (^DJISpeakerFileListStateBlock) (DJIMediaFileListState state)
Description:
Block to receive the speaker's file list.
typedef block DJISpeakerStateBlock
typedef void (^DJISpeakerStateBlock) (DJISpeakerState* state)
Description:
Block to receive the speaker's state.
enum DJISpeakerPlayMode
typedef NS_ENUM (uint8_t, DJISpeakerPlayMode)
Header: DJIAccessoryBaseTypes.h
Description:
The speaker's play mode. It determines the behavior of the speaker when it finishes playing a file.
Enum Members:
DJISpeakerPlayModeSingleOnceThe speaker will play the selected file once. The speaker will stop playing after finishing playing the file. DJISpeakerPlayModeRepeatSingleThe speaker will play the selected file repeatedly. DJISpeakerPlayModeUnknownUnknown.
enum DJISpeakerPlayingState
typedef NS_ENUM (uint8_t, DJISpeakerPlayingState)
Header: DJIAccessoryBaseTypes.h
Description:
The speaker's Playing State.
Enum Members:
DJISpeakerPlayingStatePlayingThe speaker is playing the voice. DJISpeakerPlayingStateStoppedThe speaker is stopped and playing nothing. DJISpeakerPlayingStateUnknownUnknown.
enum DJISpeakerDataTransmissionState
typedef NS_ENUM (uint8_t, DJISpeakerDataTransmissionState)
Header: DJIAccessoryBaseTypes.h
Description:
Data transmission state of the speaker.
Enum Members:
DJISpeakerDataTransmissionStateIdleThe speaker is in idle state and is ready for receiving data from the mobile device. Call startTransmissionWithInfo:startBlock:onProgress:finish:failure
to start the data transmission. DJISpeakerDataTransmissionStateReadyToTransmitThe data transmission from the mobile device to the speaker is started. Call paceData
to transmit data. DJISpeakerDataTransmissionStateTransmittingThe mobile device is transmitting data to the speaker. DJISpeakerDataTransmissionStateUnknownUnknown state, either the speaker is disconnected or not recognized.