DJI Mobile SDK Documentation

      class DJISpeaker

      @interface DJISpeaker : DJIBaseComponent
      Header:DJISpeaker.h
      Inherits From:DJIBaseComponent
      Description:

      The class represents the speaker accessory on the aircraft. Used transmit audio files and control the speaker.

      Class Members:
      File List State
      property
      property fileListState
      @property (nonatomic, readonly) DJIMediaFileListState fileListState
      Header:DJISpeaker.h
      Description:

      Current file list state of the speaker.

      See Also:

      DJIMediaFileListState

      Data Transmission State
      property
      property dataTransmissionState
      @property (nonatomic, readonly) DJISpeakerDataTransmissionState dataTransmissionState
      Header:DJISpeaker.h
      Description:

      The data transmission state of the speaker.

      See Also:

      DJISpeakerDataTransmissionState

      Set Volume
      method
      method setVolume:withCompletion
      - (void)setVolume:(NSUInteger)volume withCompletion:(DJICompletionBlock)completion
      Header:DJISpeaker.h
      Description:

      Sets the volume to play audio. The valid range is [0, 100]. 100 means loudest.

      Input Parameters:
      NSUInteger volumeVolume value to set.
      DJICompletionBlock completionCompletion block to receive the result.
      Set Play Mode
      method
      method setPlayMode:withCompletion
      - (void)setPlayMode:(DJISpeakerPlayMode)playMode withCompletion:(DJICompletionBlock)completion
      Header:DJISpeaker.h
      Description:

      Sets the play mode of the speaker to control the behavior after finishing playing a file.

      Input Parameters:
      DJISpeakerPlayMode playModeThe play mode to set.
      DJICompletionBlock completionCompletion block to receive the result.
      method startTransmissionWithInfo:startBlock:onProgress:finish:failure
      - (void)startTransmissionWithInfo:(DJIAudioFileInfo *)info
      startBlock:(DJISpeakerTransmissionStartBlock)startBlock
      onProgress:(DJISpeakerTransmissionOnProgressBlock)progressBlock
      finish:(DJISpeakerTransmissionFinishBlock)finishBlock
      failure:(DJISpeakerTransmissionFailureBlock)failureBlock
      Header:DJISpeaker.h
      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.

      Input Parameters:
      DJIAudioFileInfo * infoThe information of the file to transmit. It is also used to determine the location the file will be stored in the aircraft.
      DJISpeakerTransmissionStartBlock startBlockCalled when the transmission starts and the aircraft is ready to receive data of the audio file from the mobile device.
      DJISpeakerTransmissionOnProgressBlock progressBlockCalled to update the transmission progress. The progress is updated when a chunk of data is received successfully by the aircraft.
      DJISpeakerTransmissionFinishBlock finishBlockCalled when the transmission finishes successfully.
      DJISpeakerTransmissionFailureBlock failureBlockCalled when the transmission is interrupted by an error.
      Pace Data
      method
      method paceData
      - (BOOL)paceData:(NSData *)data
      Header:DJISpeaker.h
      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.

      Input Parameters:
      NSData * dataRaw PCM data stream in bytes.
      Return:
      BOOLYES if data is paced successfully. Otherwise, pacing data is not in the current state or the data size is illegal.
      Mark EOF
      method
      method markEOF
      - (NSError *)markEOF
      Header:DJISpeaker.h
      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
      Header:DJISpeaker.h
      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
      Header:DJISpeaker.h
      Description:

      Starts to play the audio file with the specific index.

      Input Parameters:
      NSUInteger fileIndexThe file index of the AudioMediaFile to play.
      DJICompletionBlock completionCompletion block to receive the result.
      Stop Audio Play
      method
      method stopAudioPlayWithCompletion
      - (void)stopAudioPlayWithCompletion:(DJICompletionBlock)completion
      Header:DJISpeaker.h
      Description:

      Stops the speaker from playing audio. The method is only valid when the playing state is DJISpeakerPlayingStatePlaying.

      Input Parameters:
      DJICompletionBlock completionCompletion block to receive the result.
      method rename:index:withCompletion
      - (void)rename:(NSString *)fileName index:(NSUInteger)index withCompletion:(DJICompletionBlock)completion
      Header:DJISpeaker.h
      Description:

      Renames the audio file with the specific index. If the operation is started successfully, FileListState will become DJIMediaFileListStateRenaming.

      Input Parameters:
      NSUInteger indexThe index of the audio file to rename.
      NSString * fileNameThe new file name of the audio file. The file name should not exceed 128 characters.
      DJICompletionBlock completionCompletion block to receive the result.
      Get File List Snapshot
      method
      method fileListSnapshot
      - (NSArray<DJIAudioMediaFile*> *)fileListSnapshot
      Header:DJISpeaker.h
      Description:

      Returns a copy of the current audio file list from the storage. Returns null if fileListState is reset.

      Return:
      NSArray<DJIAudioMediaFile*> *An array of DJIAudioMediaFile objects.
      Refresh File List
      method
      method refreshFileListWithCompletion
      - (void)refreshFileListWithCompletion:(DJICompletionBlock)completion
      Header:DJISpeaker.h
      Description:

      Refresh the audio file list in the aircraft.
      - If the current state is DJIMediaFileListStateReset, SDK will try to fetch the complete file list.
      - If the current state is DJIMediaFileListStateIncomplete, SDK will only fetch the missing list of files.
      - If the operation is started successfully, the DJIMediaFileListState will become DJIMediaFileListStateSyncing.
      - When the file list is refreshed successfully, the DJIMediaFileListState will become DJIMediaFileListStateUpToDate.

      Input Parameters:
      DJICompletionBlock completionCompletion block to receive the result.
      method deleteFiles:withCompletion
      - (void)deleteFiles:(NSArray<NSNumber*> *)fileIndices withCompletion:(void (^_Nullable)(NSArray<NSNumber*> *_Nonnull failedFiles, NSError *_Nullable error))completion
      Header:DJISpeaker.h
      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.

      Input Parameters:
      NSArray<NSNumber*> * fileIndicesA list of AudioMediaFile's index.
      NSArray<NSNumber*> *_Nonnull failedFilesDelete failed files.
      NSError *_Nullable errorError deleting the files.
      void (^_Nullable)(NSArray<NSNumber*> *_Nonnull failedFiles, NSError *_Nullable error) completionCompletion 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
      Header:DJISpeaker.h
      Description:

      Adds listener to receive the latest state of the speaker.

      Input Parameters:
      id listenerThe listener to receive the state. SDK will add reference count of the listener. Call removeSpeakerStateListener to release the resource.
      nullable dispatch_queue_t queueThe queue to execute the block. Pass NULL to use the default queue.
      DJISpeakerStateBlock blockBlock that will be executed when the state is updated.
      Remove Speaker State Listener
      method
      method removeSpeakerStateListener
      - (void)removeSpeakerStateListener:(id)listener
      Header:DJISpeaker.h
      Description:

      Removes the listener of the speaker state.

      Input Parameters:
      id listenerThe 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
      Header:DJISpeaker.h
      Description:

      Adds listener to receive the latest file list state of the speaker.

      Input Parameters:
      id listenerThe listener to receive the state. SDK will add reference count of the listener. Call removeFileListStateListener to release the resource.
      nullable dispatch_queue_t queueThe queue to execute the block. Pass 'NULL' to use the default queue.
      DJISpeakerFileListStateBlock blockBlock that will be executed when the state is updated.
      Remove File List State Listener
      method
      method removeFileListStateListener
      - (void)removeFileListStateListener:(id)listener
      Header:DJISpeaker.h
      Description:

      Removes the listener of the speaker file list state.

      Input Parameters:
      id listenerListener to be removed.
      typedef block DJISpeakerTransmissionStartBlock
      typedef void (^DJISpeakerTransmissionStartBlock) ()
      Header:DJISpeaker.h
      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)
      Header:DJISpeaker.h
      Description:

      Called to update the transmission progress. The progress is updated when a chunk of data is received successfully by the aircraft.

      Input Parameters:
      NSInteger dataSizeThe accumulated data size of the audio file received by the aircraft.
      typedef block DJISpeakerTransmissionFinishBlock
      typedef void (^DJISpeakerTransmissionFinishBlock) (NSInteger index)
      Header:DJISpeaker.h
      Description:

      Called when the transmission finishes successfully.

      Input Parameters:
      NSInteger indexThe index assigned by the aircraft for the new audio file.
      typedef block DJISpeakerTransmissionFailureBlock
      typedef void (^DJISpeakerTransmissionFailureBlock) (NSError *error)
      Header:DJISpeaker.h
      Description:

      Called when the transmission is interrupted by an error.

      Input Parameters:
      NSError * errorThe possible error during the transmission.
      typedef block DJISpeakerFileListStateBlock
      typedef void (^DJISpeakerFileListStateBlock) (DJIMediaFileListState state)
      Header:DJISpeaker.h
      Description:

      Block to receive the speaker's file list.

      Input Parameters:
      DJIMediaFileListState stateAn enum value of DJIMediaFileListState.
      typedef block DJISpeakerStateBlock
      typedef void (^DJISpeakerStateBlock) (DJISpeakerState* state)
      Header:DJISpeaker.h
      Description:

      Block to receive the speaker's state.

      Input Parameters:
      DJISpeakerState* stateAn object of DJISpeakerState.
      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.