Chirp SDK

class chirpsdk.ChirpSDK(key=None, secret=None, config=None, debug=False, block=None)[source]

The Chirp Python SDK.

This is the main wrapper around the Chirp Library. It exposes methods to send arbitrary payloads, and receive decoded chirps from the audio layer. Received data is handled in callback methods using the CallbackSet.

A full getting started guide for the Chirp Python SDK can be found at https://developers.chirp.io/docs/getting-started/python

You can set the SDK to run in debug mode by setting the flag true. This will write any input data from the microphone to a wav file called chirp_audio.wav.

Parameters:
  • key (str) – Chirp application key
  • secret (str) – Chirp application secret
  • config (str) – Path to config file or config string
  • debug (bool) – Enter debug mode
  • block (str) – Select a different block from your ~/.chirprc other than [default]
channel_count

int – Returns the number of channels supported by the current configuration.

close()[source]

Frees memory used by the Chirp Library.

Raises:ChirpSDKError – If an error occurs when freeing memory.
expiry

datetime – Returns the expiry date of the current configuration.

get_duration(length)[source]

float: Returns the duration of a chirp of length bytes in seconds.

get_state_for_channel(channel)[source]

int: Property to get the current state of a channel.

Returns either
chirpsdk.CHIRP_SDK_STATE_NOT_CREATED chirpsdk.CHIRP_SDK_STATE_STOPPED chirpsdk.CHIRP_SDK_STATE_RUNNING chirpsdk.CHIRP_SDK_STATE_SENDING chirpsdk.CHIRP_SDK_STATE_RECEIVING
input_sample_rate

int – Property to get/set the SDK input sample rate.

is_offline

bool – Returns true if configured in offline mode.

is_valid(payload)[source]

Check if a payload is valid.

Parameters:payload (Payload) – The Chirp Payload (bytearray)
Returns:bool – True if valid.
listen_to_self

bool – Property to get/set the self listening function of the SDK.

Setting this property to True will cause the SDK to hear its own chirps, thus the received callbacks will be triggered when sending data. This is False by default.

load_config(filename)[source]

Load a config from file, and initialise the Chirp Library.

This must be done after immediately after instantiating the SDK. Unless you are implementing your own audio layer, then the audio attribute must be set first.

Parameters:filename (str) – The path to the config file
Raises:ChirpSDKError – If the config is invalid or there is an error setting the callbacks.
max_payload_length

int – Property to get the max payload length available with the current configuration.

new_payload(data=None)[source]

Generate an arbitrary Chirp Payload. A Chirp Payload is subclass of the built in type (bytearray). It will accept the same data types as a bytearray, ie. an integer, a string or an array of bytes.

Parameters:data – The payload data
Returns:payload (Payload) – The Chirp Payload (bytearray)
Raises:ValueError – If the data length is longer than the max payload length. This is set by the config. Or if there is no data.
output_sample_rate

int – Property to get/set the SDK output sample rate.

process_input(input)[source]

Process input data only. Used for receive only mode.

An input array of floating-point audio samples should be passed in. The Chirp Library will trigger the callback methods if any chirps are decoded. The input data must contain values ranging from -1 to +1, and must be sampled at the same rate as the SDK’s input_sample_rate property.

Parameters:input (bytes) – The input audio data as a string of bytes.
Raises:ChirpSDKError – If there is an error processing the data.
process_output(output)[source]

Process output data only. Used for send only mode.

An output array should be passed by reference. The Chirp Library will populate the output buffer with any data to be sent. The data will be sampled at the SDK’s output_sample_rate property.

Parameters:output (buffer) – The output buffer to be populated.
Raises:ChirpSDKError – If there is an error processing the data.
process_shorts_input(input)[source]

Process input data only. Used for receive only mode.

An input array of 16bit signed integer audio samples should be passed in. The Chirp Library will trigger the callback methods if any chirps are decoded. The input data must contain values ranging from -32767 to +32767, and must be sampled at the same rate as the SDK’s input_sample_rate property.

Parameters:input (bytes) – The input audio data as a string of bytes.
Raises:ChirpSDKError – If there is an error processing the data.
process_shorts_output(output)[source]

Process output data only. Used for send only mode.

An output array should be passed by reference. The Chirp Library will populate the output buffer with any data to be sent. The data will be sampled at the SDK’s output_sample_rate property.

Parameters:output (buffer) – The output buffer to be populated.
Raises:ChirpSDKError – If there is an error processing the data.
protocol_name

str – Property to get the configured protocol name.

protocol_version

int – Returns the current protocol version.

random_payload(length=None)[source]

Generate a random Chirp Payload of length bytes If no length is specified, then a payload of a random length (up to the max_payload_length) is generated.

Parameters:length – The required length of the payload (optional)
Returns:Payload – A Chirp Payload containing random data (bytearray)
read_chirprc(block='default')[source]

Read the contents of the ~/.chirprc file to retrieve application key, secret and configuration.

Parameters:

block (str) – The block name in ~/.chirprc to use

Raises:
  • IOError – If no ~/.chirprc file exists
  • ValueError – If there is an error parsing the file
send(payload, blocking=False)[source]

Send a Chirp Payload. This will pass the payload data to the Chirp Library, which will then be processed into the output buffer in the process functions. The data will be transmitted asynchronously, unless the blocking flag is set to True.

Parameters:
  • payload (Payload) – The Chirp Payload (bytearray)
  • blocking (bool) – True to block until send has completed
Raises:
  • RuntimeError – If sending was not enabled when starting the SDK.
  • ChirpSDKError – If there is an error sending the data.
set_callbacks(callbacks)[source]

Set the callback set, used for consistency between platforms.

Parameters:callbacks – (CallbackSet): Callback set
Raises:ChirpSDKError – If there is an error setting the callbacks.
set_config(config)[source]

Initialise the Chirp Library with a config.

This sets up the config and the internal callback set. If using the default sounddevice audio layer, then this is instantiated here.

Parameters:config (str) – config string
Raises:ChirpSDKError – If the config is invalid or there is an error setting the callbacks.
set_config_from_network(name=None)[source]

Retrieve a config for your application, and initialise the Chirp Library. If no config name is specified, then the default config is used.

Parameters:

name (str) – config name, default is used if not set

Raises:
  • ChirpSDKNetworkError – If the request to retrieve the config fails.
  • ChirpSDKError – If the config is invalid or there is an error setting
  • the callbacks.
set_random_seed(seed=None)[source]

Set the seed for the pseudo-random number generator, used to generate random payloads.

Parameters:seed (int) – initial seed to use, or random if None
start(send=True, receive=True)[source]

Start the SDK running.

The SDK can be configured to run in send mode, receive mode or both. The default is send and receive mode. This also calls the start method in the audio layer.

Parameters:
  • send (bool) – Enable send mode
  • receive (bool) – Enable receive mode
Raises:

ChirpSDKError – If there is an error starting the Chirp Library.

state

int – Property to get the current state of the SDK.

Returns either
chirpsdk.CHIRP_SDK_STATE_NOT_CREATED chirpsdk.CHIRP_SDK_STATE_STOPPED chirpsdk.CHIRP_SDK_STATE_RUNNING chirpsdk.CHIRP_SDK_STATE_SENDING chirpsdk.CHIRP_SDK_STATE_RECEIVING
stop()[source]

Stop the SDK and audio streams.

Raises:ChirpSDKError – If there is an error stopping the Chirp Library.
transmission_channel

int – Property to get/set the transmission channel on which data is sent.

trigger_callbacks(payload)[source]

Trigger the callback methods with a payload.

Parameters:payload (bytearray) – The data for the simulation.
version

Get version information from the Chirp Library.

Returns:dict – Version information for Chirp libraries.
volume

float – Property to get/set the SDK volume.

Callbacks

class chirpsdk.CallbackSet[source]

An abstract class to implement callback methods.

The ChirpSDK will call these methods when it is changing state, or is sending/receiving data. To handle data events you should inherit from this class, and pass the object into the chirpsdk.ChirpSDK.set_callbacks() method.

on_received(payload, channel)[source]

Called when the Chirp Library has decoded a full payload. Note: A length of 0 indicates a failed decode.

Parameters:
  • payload (Payload) – The Chirp Payload (bytearray)
  • channel (int) – The channel on which the data has being received
on_receiving(channel)[source]

Called when the Chirp Library hears the start of a payload.

Parameters:channel (int) – The channel on which the data is being received
on_sending(payload, channel)[source]

Called when the Chirp Library has begun sending data.

Parameters:
  • payload (Payload) – The Chirp Payload (bytearray)
  • channel (int) – The channel on which the data is being sent
on_sent(payload, channel)[source]

Called when the Chirp Library has sent the whole payload.

Parameters:
  • payload (Payload) – The Chirp Payload (bytearray)
  • channel (int) – The channel on which the data is sent
on_state_changed(old, new)[source]

Called when the state of Chirp Library has changed.

Parameters:
  • old (str) – Previous state
  • new (str) – Current state

Advanced

class chirpsdk.AudioSet(sdk)[source]

An abstract class for overriding the default audio layer.

The ChirpSDK uses sounddevice to handle audio streams. If you need to provide your own audio layer then you should subclass this, and assign it to the audio attribute of the SDK before loading the config.

The Audio layer must provide methods to start/stop the input/output streams. These will be called by SDK appropriately.

The Audio layer should call the chirpsdk.ChirpSDK.process_input() method when input audio is available from the microphone, and chirpsdk.ChirpSDK.process_output() when audio should to be sent to the speaker.

start(send=True, receive=True)[source]

Start the audio engine.

Parameters:
  • send (bool) – Enable output audio
  • receive (bool) – Enable input audio
stop()[source]

Stop the audio engine.

Index