ChirpSDK

@interface ChirpSDK : NSObject

The main Chirp SDK class. Use this to send and receive data using sound. Only one single instance should be instantiated per application.

  • The volume of the Chirp SDK within your application. This is not the overall system volume, just the volume of the chirp output into the main audio mix. Valid values are between 0.0 and 1.0.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) float volume;

    Swift

    var volume: Float { get set }
  • The volume of the OS hardware volume. Valid values are between 0.0 and 1.0.

    Warning

    Not currently supported on macOS

    Declaration

    Objective-C

    @property (readonly, nonatomic) float systemVolume;

    Swift

    var systemVolume: Float { get }
  • The maximum payload size, in bytes, that the SDK’s current config permits.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger maxPayloadLength;

    Swift

    var maxPayloadLength: UInt { get }

    Return Value

    The maximum number of bytes able to be sent by the SDK’s current config.

  • The number of channels supported by the current protocol. Each channel corresponds to a different frequency band. Standard Chirp protocols typically only support a single channel. See how many channels a protocol supports at https://developers.chirp.io/applications

    Declaration

    Objective-C

    @property (readonly, atomic) NSUInteger channelCount;

    Swift

    var channelCount: UInt { get }
  • The current channel number that Chirp signals are being sent over. Each channel corresponds to a different frequency band. Defaults to zero. Standard Chirp protocols typically only support a single channel. See how many channels a protocol supports at https://developers.chirp.io/applications

    Declaration

    Objective-C

    - (NSUInteger)transmissionChannel;

    Swift

    func transmissionChannel() -> UInt
  • Set the current transmission channel. Each channel corresponds to a different frequency band. Defaults to zero. Standard Chirp protocols typically only support a single channel. See how many channels a protocol supports at https://developers.chirp.io/applications

    Declaration

    Objective-C

    - (NSError *_Nullable)setTransmissionChannel:(NSUInteger)channel;

    Swift

    func setTransmissionChannel(_ channel: UInt) -> Error?

    Parameters

    channel

    The index to set. Must be less than the maximum number of supported channels, as indicated by channelCount.

    Return Value

    nil if the channel is valid, or an NSError otherwise.

  • Get the current state of the SDK.

    Declaration

    Objective-C

    @property (readonly, atomic) CHIRP_SDK_STATE state;

    Swift

    var state: CHIRP_SDK_STATE { get }
  • Get the current state of the SDK for a given channel. If the channel does not exist, CHIRP_SDK_STATE_NOT_CREATED is returned.

    Declaration

    Objective-C

    - (CHIRP_SDK_STATE)stateForChannel:(NSUInteger)channel;

    Swift

    func state(forChannel channel: UInt) -> CHIRP_SDK_STATE
  • The full version string of the SDK and audio engine.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull version;

    Swift

    var version: String { get }
  • Information on the current audio transmission settings.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull info;

    Swift

    var info: String { get }
  • Initialise the SDK. Sign up for credentials at the Chirp developer hub: https://developers.chirp.io/

    Declaration

    Objective-C

    - (ChirpSDK *_Nullable)initWithAppKey:(NSString *_Nonnull)key
                                andSecret:(NSString *_Nonnull)secret;

    Swift

    init?(appKey key: String, andSecret secret: String)
  • Set the config to use within the SDK. This configures audio transmission properties, and must be done before starting the SDK via the start method.

    Config strings can be downloaded from the Chirp developer hub at https://developers.chirp.io.

    Note that this method also authenticates your application with Chirp’s auth servers. For completely offline operation, please get in touch at contact@chirp.io.

    Declaration

    Objective-C

    - (NSError *_Nullable)setConfig:(NSString *_Nonnull)config;

    Swift

    func setConfig(_ config: String) -> Error?

    Parameters

    config

    A valid, non-nil config NSString

    Return Value

    nil if the configuration is set successfully, or an error

  • Set your default app config by fetching it from the Chirp REST API. This should typically only be used in cases in which you want your configuration to be generated dynamically – for example, if you are rapidly prototyping different transmission settings with Chirp.

    Declaration

    Objective-C

    - (void)setConfigFromNetworkWithCompletion:
        (ChirpSetConfigFromNetworkBlock _Nonnull)completion;

    Swift

    func setConfigFromNetworkWithCompletion(_ completion: @escaping ChirpSetConfigFromNetworkBlock)

    Parameters

    completion

    A non-nil ChirpSetConfigFromNetworkBlock completion handler.

  • Start the SDK running. This must be done before sending or receiving data using the SDK instance.

    Warning

    A config must be set before calling this method

    Declaration

    Objective-C

    - (NSError *_Nullable)start;

    Swift

    func start() -> Error?

    Return Value

    nil if the engine is started, otherwise an NSError.

  • Start the SDK running in Send, Receive or SendAndReceive mode. In Send mode, microphone permissions will not be required. Input audio will not be processed in Send mode, likewise output audio will not be processed in Receive mode.

    Warning

    A config must be set before calling this method

    Declaration

    Objective-C

    - (NSError *_Nullable)startInMode:(ChirpAudioMode)mode;

    Swift

    func start(in mode: ChirpAudioMode) -> Error?

    Parameters

    mode

    ChirpAudioModeSend, ChirpAudioModeReceive or ChirpAudioModeSendAndReceive mode

    Return Value

    nil if the engine is started, otherwise an NSError.

  • Stop the SDK running.

    Declaration

    Objective-C

    - (NSError *_Nullable)stop;

    Swift

    func stop() -> Error?

    Return Value

    nil if the SDK has started successfully, otherwise an NSError.

  • Stop the SDK running.

    Declaration

    Objective-C

    - (void)stopWithCompletion:(ChirpStoppedBlock _Nonnull)completion;

    Swift

    func stop(completion: @escaping ChirpStoppedBlock)

    Parameters

    completion

    A block called when the SDK has fully finished processing and stopped all audio IO.

  • Set whether or not to mix playing audio with Chirp data (such as the Music app). Note that by default the SDK will route all audio to the device’s speaker on start. Defaults to NO.

    Warning

    This must be set before calling start.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL shouldMixAudio;

    Swift

    var shouldMixAudio: Bool { get set }
  • Override current audio settings to force audio to external peripherals as opposed to the device’s speaker. Defaults to NO.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL routeAudioToExternalPeripherals;

    Swift

    var routeAudioToExternalPeripherals: Bool { get set }
  • Deactivate the audio session when stopping the SDK. This should be set to NO if the shared AVAudioSession is in use elsewhere in your app. Defaults to YES

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL shouldDeactivateAudioSession;

    Swift

    var shouldDeactivateAudioSession: Bool { get set }
  • Send data. The data parameter must be a non-nil NSData instance that is valid for the currently configured SDK. The data instance’s validity for sending can be checked using the isValidPayload: instance method.

    Declaration

    Objective-C

    - (NSError *_Nullable)send:(NSData *_Nonnull)data;

    Swift

    func send(_ data: Data) -> Error?

    Parameters

    data

    The data to be sent

    Return Value

    CHIRP_SDK_OK will start sending the data.

  • A block called when sending starts. It is passed the NSData being sent and the NSUInteger channel the data is sent on.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic) ChirpSendingBlock _Nullable sendingBlock;

    Swift

    var sendingBlock: ChirpSendingBlock? { get set }
  • A block called when sending ends. It is passed the NSData that was sent and the NSUInteger channel the data was sent on.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic) ChirpSentBlock _Nullable sentBlock;

    Swift

    var sentBlock: ChirpSentBlock? { get set }
  • A block called when receiving starts. It is passed the NSUInteger channel the data is being received on.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
        ChirpReceivingBlock _Nullable receivingBlock;

    Swift

    var receivingBlock: ChirpReceivingBlock? { get set }
  • A block called when receiving ends. It is passed the received NSData and the NSUInteger channel the data was received on, or nil if the decode operation has failed.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
        ChirpReceivedBlock _Nullable receivedBlock;

    Swift

    var receivedBlock: ChirpReceivedBlock? { get set }
  • A block called when sending/receiving state changes. It is passed the old and new states.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
        ChirpStateUpdatedBlock _Nullable stateUpdatedBlock;

    Swift

    var stateUpdatedBlock: ChirpStateUpdatedBlock? { get set }
  • A block called when system volume changes, and when the SDK is started via the start: method. This will be a value between 0.0f and 1.0f, or -1.0f in an error condition.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
        ChirpVolumeChangedBlock _Nullable systemVolumeChangedBlock;

    Swift

    var systemVolumeChangedBlock: ChirpVolumeChangedBlock? { get set }
  • A block called when audio samples are ready.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
        ChirpAudioBufferUpdatedBlock _Nullable audioBufferUpdatedBlock;

    Swift

    var audioBufferUpdatedBlock: ChirpAudioBufferUpdatedBlock? { get set }
  • A block called when the SDK’s authentication state is updated after initialisation, passed the nullable config dictionary and error.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
        ChirpAuthenticatedBlock _Nullable authenticatedBlock;

    Swift

    var authenticatedBlock: ChirpAuthenticatedBlock? { get set }
  • The duration in seconds for a specified payload length in bytes.

    Declaration

    Objective-C

    - (NSTimeInterval)durationForPayloadLength:(NSUInteger)length;

    Swift

    func duration(forPayloadLength length: UInt) -> TimeInterval
  • Check whether a non-nil NSData instance is valid and able to be sent using the Chirp SDK as it is currently configured via its config file.

    Declaration

    Objective-C

    - (BOOL)isValidPayload:(NSData *_Nonnull)data;

    Swift

    func isValidPayload(_ data: Data) -> Bool

    Parameters

    data

    A non-nil NSData instance

    Return Value

    YES is the data instance is valid for sending

  • Generate random data which is guaranteed to be valid for the Chirp SDK’s current config.

    Declaration

    Objective-C

    - (NSData *_Nullable)randomPayloadWithLength:(NSUInteger)length;

    Swift

    func randomPayload(withLength length: UInt) -> Data?

    Parameters

    length

    the length of the payload to generate in bytes.

    Return Value

    NSData NSData instance with random bytes, or nil if an invalid length is specified.

  • Generate random data with random length which is guaranteed to be valid for the Chirp SDK’s current config. Similar to running the randomPayloadWithLength:0

    Declaration

    Objective-C

    - (NSData *_Nonnull)randomPayloadWithRandomLength;

    Swift

    func randomPayloadWithRandomLength() -> Data

    Return Value

    NSData A non-nil, valid NSData instance with random bytes.

  • Set the random seed used by the SDK. This is useful if you want to control the sequence of random payloads generated by randomData.

    Declaration

    Objective-C

    - (void)setRandomSeed:(NSUInteger)seed;

    Swift

    func setRandomSeed(_ seed: UInt)

    Parameters

    seed

    A positive integer.