libaudiogum 3.8.0

The Audiogum Embedded C SDK.

You can obtain the source and example programs at https://github.com/audiogum/libaudiogum.

Functions that return a structure have an accompanying ag_free function to release memory.

An OAuth2 access_token will be acquired automatically within the library when calling the Audiogum platform.

Before any other function, ag_init must be called to set your credentials and device information.

An example C firmware implementation covering playback and voice control is available at https://github.com/audiogum/ag-fw.

Functions

Initialize Library

Initializes the library with your device details - must be called before any other function call.

Calling ag_free is required to free resources allocated in this function.

No HTTP connections are made in this function.

void ag_init(char *client_id, char *client_secret, char *os_name, char *os_version, char *device_type, char *firmware_version, char *device_id, char *data_path)

Parameters

client_id The client_id issued by Audiogum.
client_secret The client_secret issued by Audiogum.
os_name The device Operating System name to be used for analytics purposes.
os_version The device Operating System version to be used for analytics purposes.
device_type The device type version to be used for analytics purposes and firmware version checking.
firmware_version The device firmware version to be used for analytics purposes and firmware version checking.
device_id The unique device id to be used for analytics purposes and identification. Typically this will be the device mac address.
data_path The path (with no trailing slash) where libaudiogum can store data for this device.

Free Library Resources

Free up access_token and other internal memory allocated.

void ag_free()

Get Version

Get the library version number.

char *ag_get_version()

Returns

char* containing the library version.

Has Access Token

Gets whether the library has obtained a valid access_token - attempts to get one if not obtained yet. Useful for checking connection problems.

bool ag_has_access_token()

Returns

bool indicating whether the library has a valid access_token.

Check Expiry

Utility function that returns a boolean indicating whether a time value has expired. We at least a minute window around the expiry.

bool ag_has_expired(time_t expiry)

Parameters

expiry The time to check

Returns

bool indicating whether the time value has expired.

Get Device Location

Look up device location from IP address.

ag_ip_location *ag_get_location_from_ip()

Returns

ag_ip_location structure containing location information.

Free Location Details

void ag_free_ip_location(ag_ip_location *location)

Parameters

location The location details to free.

Get Custom Configuration

Get arbitrary cloud-based configuration for a specific key. This allows your firmware to adapt to cloud-based configuration at run time.

char *ag_get_custom_config (const char *key)

Parameters

key The key to get config for

Returns

char* string containing the config value, if available. Caller must free the return value.

Check Firmware Version

Check for new firmware versions based on the current version.

ag_firmware *ag_check_firmware_version(const char *region)

Parameters

region The region to check for firmware in (this can be obtained with the ag_get_location_from_ip function)

Returns

ag_firmware structure containing update information if available.

Free Firmware Details

void ag_free_firmware(ag_firmware *fw)

Parameters

fw The firmware details to free.

Update Device Info

Updates the cloud details held about the device.

ag_response *ag_update_device_info(ag_device_info *info)

Parameters

info The device information

Returns

ag_response structure containing the response code and optional error from the API call.

Free Response Details

void ag_free_response(ag_response *response)

Parameters

response The response to free.

Get Playable Items

Get the next set of items to play for a playable.

ag_playable_items *ag_get_playable_items(const char *playable_id)

Parameters

playable_id The ID of the playable to fetch items for

Returns

ag_playable_items structure containing details on the playable as well as items to play.

Get Playable Items From Index

Get the next set of items to play for a playable, starting at a specific index.

ag_playable_items *ag_get_playable_items_from_index(const char *playable_id,int start_index)

Parameters

playable_id The ID of the playable to fetch items for
start_index The start index to fetch items from

Returns

ag_playable_items structure containing details on the playable as well as items to play.

Get Playable Service Details

Helper function to get the specified service from an existing playable. Caller should not free the structure returned.

ag_service_auth *ag_get_playable_service_auth(ag_playable_items* playable, const char *service)

Parameters

playable The playable to extract the service details from
service The service id

Returns

ag_service_auth structure containing the service details.

Free Playable Items

void ag_free_playable_items(ag_playable_items *items)

Parameters

items The items to free.

Refresh Stream URL

Refreshes a time-limited stream url for a specific item - used when you notice an item is about to expire.

char *ag_refresh_playable_stream_url(const char *playable_id, ag_playable_item *item)

Parameters

playable_id The ID of the playable to fetch items for
item The item to refresh

Returns

char * containing the new stream url if the call succeeded.

Refresh Service Auth Details

Refreshes time-sensitive auth details for a specific service - used when you notice auth details are about to expire.

ag_service_auth *ag_refresh_playable_service_auth(const char *playable_id, const char *service_id)

Parameters

playable_id The ID of the playable to fetch items for
service_id The service to refresh auth details for

Returns

ag_service_auth structure containing updated auth details.

Free Service Auth Details

void ag_free_service_auth(ag_service_auth *auth)

Parameters

auth The items to free.

Populate Play Analytics Event

Populates an already-allocated ag_event structure with details to send as an analytics event.

void ag_populate_play_event(ag_event *event, AG_EVENT_ACTION action, AG_EVENT_CONNECTION_TYPE connection_type, char *playable_analytics_json, int preset, ag_playable_item *playable_item, int offset)

Parameters

event - a pointer to a pre-allocated event structure
action - the play action that occurred - see action types
connection_type - the connection type that was active when the event occurred
playable_analytics_json - the analytics_json obtained from ag_playable_items
preset - the preset number the playback started from
playable_item - the item being played (where appropriate)
offset - the offset in the item being played at which time the event occurred

Populate External Play Analytics Event

Populates an already-allocated ag_event structure with details of an externally played item to send as an analytics event.

void ag_populate_external_play_event(ag_event *event, AG_EVENT_ACTION action, AG_EVENT_CONNECTION_TYPE connection_type, AG_EVENT_PLAY_SOURCE_TYPE source_type, char* source_service, char* source_ref, char* source_name, int preset, ag_playable_item *playable_item, int offset)

Parameters

event - a pointer to a pre-allocated event structure
action - the play action that occurred - see action types
connection_type - the connection type that was active when the event occurred
source_type - the playback source type
source_service - the optional service being played from
source_ref - the optional ID of the container item being played - e.g. a playlist or album
source_name - the optional name of the container item being played - e.g. a playlist or album
preset - the preset number the playback started from
playable_item - details about the item being played (where appropriate)
offset - the offset in the item being played at which time the event occurred

Populate Voice Analytics Event

Populates an already-allocated ag_event structure with details to send as an analytics event.

void ag_populate_voice_event(ag_event *event, AG_EVENT_ACTION action, AG_EVENT_CONNECTION_TYPE connection_type, AG_EVENT_VOICE_STOPPED_BY stopped_by)

Parameters

event - a pointer to a pre-allocated event structure
action - the action that occurred - see action types - in this case success or failure
connection_type - the connection type that was active when the event occurred
stopped_by - how the audio recording was stopped

Send Analytics Events

Sends a pre-prepared batch of analytics events. We recommend batching analytics events into groups of around 5 to save processing / network interaction.

ag_response *ag_send_events(ag_event *events, int num_events)

Parameters

events a pointer to the array of events
num_events The number of events in the array to send

Returns

ag_response structure containing the response code and optional error from the API call.

Free Event Internals

Frees internally allocated memory on play events created by ag_populate_play_event or ag_populate_voice_event. Caller is responsible for free'ing each ag_event.

void ag_free_event_internals(ag_event *events, int num_events)

Parameters

events a pointer to the array of events
num_events The number of events in the array to free

Start Match Job

Starts a job for matching content for the specified user catalogue.

char *ag_match_start_job(char *catalog_id)

Parameters

catalog_id - the ID of the user catalogue to send matches to

Returns

char * containing a job ID for use in ag_match_send_items. Returns NULL if there is an error or if no delegated token is available.

Populate Match Update Item

Populates an already-allocated ag_match_item structure with details to send for matching.

void ag_match_populate_update_item(ag_match_item *item, char *source_name, char *location, char *name, char *artist_display_name, char *last_modified, char *album_name, char *genre_name, int duration, int track_number)

Parameters

item - a pointer to a pre-allocated ag_match_item structure
source_name - name of the source being scanned - this would be a NAS server name, a phone identifier or similar
location - the locally addressable location of the item
name - the name of the item
artist_display_name - the artist name for the item
last_modified - the last modified time for the item
album_name - the optional album name for the item
genre_name - the optional genre name of the item
duration - the optional duration in seconds of the item
track_number - the optional track number

Populate Match Delete Item

Populates an already-allocated ag_match_item structure with details to send for matching.

void ag_match_populate_delete_item(ag_match_item *item, char *source_name, char *location)

Parameters

item - a pointer to a pre-allocated ag_match_item structure
source_name - name of the source being scanned - this would be a NAS server name, a phone identifier or similar
location - the locally addressable location of the item

Send Match Items

Sends a pre-prepared batch of match items. We recommend batching analytics events into groups of around 50 to save processing / network interaction.

ag_response *ag_match_send_items(char *job_id, ag_match_item *items, int num_items)

Parameters

job_id - the match job the items pertain to
items - a pointer to the array of items
num_items - the number of items in the array to send

Returns

ag_response structure containing the response code and optional error from the API call.

Free Match Item Internals

Frees internally allocated memory on events created by ag_match_populate_update_item or ag_match_populate_delete_item. Caller is responsible for free'ing each ag_match_item.

void ag_free_match_item_internals(ag_match_item *items, int num_items)

Parameters

items a pointer to the items to free
num_events The number of items in the array to free

Complete Match Job

Informs the Audiogum platform that the ongoing match job has completed sending metadata.

void ag_match_send_complete(char *job_id)

Parameters

job_id - the match job id

Start remote control loop

Starts a processing loop to receive control commands - clients should call this function on a new thread

void ag_start_remotecontrol_loop(AG_ACTION actions_understood, AG_PLAY_CAPABILITY play_capabilities, AG_VOICE_CAPABILITY voice_capabilities, ag_socket_state_callback state_callback, ag_action_callback action_callback)

Parameters

actions_understood - a bit-wise combination of AG_ACTION control actions this device understands
play_capabilities - a bit-wise combination of AG_PLAY_CAPABILITY playback capabilities this device has.
voice_capabilities - optional bit-wise combination of AG_VOICE_CAPABILITY voice capabilities if voice commands will be sent
state_callback - ag_socket_state_callback function pointer to call when connection state changes occur
action_callback - ag_action_callback function pointer to call when actions are received

Get remote control token

Gets the device remote control token to pass to companion apps.

char *ag_get_remotecontrol_token()

Delete remote control token

Deletes an existing device remotecontrol token in the case of revokation - e.g. if factory reset does not wipe the data_path location. Note this will not close any existing connection.

void ag_delete_remotecontrol_token()

Stop remote control loop

Stops the current remote control session.

void ag_stop_remotecontrol_loop()

`ag_socket_state_callback`

Callback function for remote control connection state changes.

void (*ag_socket_state_callback)(AG_SOCKET_STATE state)

Parameters

state - the latest AG_SOCKET_STATE

`ag_action_callback`

Callback function for when control commands are received.

void (*ag_action_callback)(ag_action *actions, int num_actions, ag_feedback *feedback, bool expect_reply)

Parameters

actions optional array of ag_action received
num_actions the number of actions received
feedback optional accompanying feeback to play or display to the user
expect_reply boolean indicating that microphone should be opened to obtain a spoken response from user.

`ag_action_respond_callback`

Callback function for when remote control commands are received that require local data to be returned. Structures and their contents will be free'd by the library.

void (*ag_action_respond_callback)(AG_ACTION action, void *response_struct)

Parameters

action - the AG_ACTION received.
response_struct - a void* pointer to a data structure to fill - this will differ depending upon the action received. The AG_ACTION states the type that will be passed.

`ag_copy_playable_details_to_player_state`

Copies playable info to the ag_player_state structure for safely sending back to remote control.

void ag_copy_playable_details_to_player_state(ag_player_state *state, char *playable_json, char *playable_item_json)

Parameters

state - the ag_player_state to populate.
playable_json - The playable analytics_json.
playable_item_json - The playable item raw_json.

`ag_player_state_to_json`

Gets player state as json for local command API usage. Result must be free'd by caller

char *ag_player_state_to_json(ag_player_state *player_state)

Parameters

player_state - the ag_player_state to transform.

`ag_handle_action_json`

Helper function to handle action commands from remote control websockets. Open to allow local command APIs to use the same parsing and infrastructure.

bool ag_handle_action_json(char *message, ag_action_callback action_callback, char **response_json)

Parameters

message - the json message received
action_callback - function to call when actions are received
response_json - a pointer to a char* that will receive the json response (when the action requires) - if NULL, the library will send back to the remote control websocket, otherwise caller must free the result.

`ag_capabilities_to_string`

Helper function to turn bit flags of understood actions into a char * for local command APIs to expose their capabilities.

char *ag_capabilities_to_string(AG_ACTION actions)

Parameters

actions - a bit-wise combination of AG_ACTION control actions this device understands

Start Voice Session

Starts a processing loop to send audio data from a user to interpret as voice commands - clients should call this function on a new thread. See Natural Language Understanding docs for an overview. Requires a Speech Token to have been stored with ag_voice_store_delegated_token

void ag_voice_open_session(char *encoding, int sample_rate, ag_voice_state_callback state_callback, ag_player_state *player_state)

Parameters

encoding - the audio encoding - pcm or flac
sample_rate - the audio sample rate - e.g. 16000
state_callback - ag_voice_state_callback function pointer to call when connection state changes occur
player_state - the current player info in a ag_player_state

Update Now Playing Data

Updates the current playback information for context of voice commands such as "what's this?". Note, this function will not free the player details.

void ag_voice_update_now_playing(ag_player_state *player_state)

Parameters

player_state - current player info

Send Voice Data

Sends raw audio data.

void ag_voice_send_mic_data(unsigned char *buffer, int length)

Parameters

buffer - the bytes to send
length - the number of bytes to send

Send Voice Data Terminator

Sends a termination message if no silence is recorded after the user talks. See Natural Language Understanding docs.

void ag_voice_send_mic_terminator()

Store Delegated Token

Stores a delegated user token for the device. See Voice authorization for more details on delegated tokens.

void ag_voice_store_delegated_token(char *response)

Parameters

response - the full JSON body returned access_token obtained from the speech token API call

Has Delegated Token

Gets whether the library has a stored delegated_token - attempts to refresh if necessary.

void ag_has_delegated_token()

Delete Delegated Token

Deletes an existing device delegated token in the case of revokation - e.g. if factory reset does not wipe the data_path location. Note this will not close any existing connection.

void ag_voice_delete_delegated_token()

Send Voice Text

Converts the text taken from a separate ASR engine into the action that should be performed. See Natural Language Understanding docs for an overview. Requires a Speech Token to have been stored with ag_voice_store_delegated_token

AG_VOICE_STATE ag_voice_send_text(char *text, char *transcription_source, AG_ACTION actions_understood, AG_PLAY_CAPABILITY play_capabilities, AG_VOICE_CAPABILITY voice_capabilities, ag_player_state *player_state, ag_action_callback action_callback)

Parameters

text - the text transcribed by the separate ASR engine
transcription_source - the source of the transcription
actions_understood - a bit-wise combination of AG_ACTION control actions this device understands
play_capabilities - a bit-wise combination of AG_PLAY_CAPABILITY playback capabilities this device has.
voice_capabilities - optional bit-wise combination of AG_VOICE_CAPABILITY voice capabilities if voice commands will be sent
player_state - the current player info in a ag_player_state
action_callback - ag_action_callback function pointer to call when actions are received

Returns

AG_VOICE_STATE containing the result state.

`ag_voice_state_callback`

Callback function for voice connection state changes.

void (*ag_voice_state_callback)(AG_VOICE_STATE state, char *text)

Parameters

state - the latest AG_VOICE_STATE
text - optional text detected - only used for AG_VOICE_STATE_ACTIVITY_PHRASE_UNDERSTOOD

Enumerations

`AG_ACTION`

Flag enumeration of values indicating control actions.

Values	Descriptions
`AG_ACTION_UNKNOWN`	Unknown action
`AG_ACTION_PLAY`	Play/resume playback, if any already started
`AG_ACTION_STOP`	Stop playback
`AG_ACTION_PAUSE`	Pause playback
`AG_ACTION_SKIP_NEXT`	Skip player to next item
`AG_ACTION_SKIP_PREV`	Skip player to previous item
`AG_ACTION_SEEK`	Move player to specified offset in seconds passed in `int_param`
`AG_ACTION_REWIND`	Re-start current item from the beginning
`AG_ACTION_VOLUMEUP`	Increase volume by one increment or by specified relative value passed in `int_param`
`AG_ACTION_VOLUMEDOWN`	Decrease volume by one increment or by specified relative value passed in `int_param`
`AG_ACTION_SETVOLUME`	Set volume to specified value passed in `int_param` (assume range 0 to 100)
`AG_ACTION_MUTE`	Mute the audio output (without changing current volume value)
`AG_ACTION_UNMUTE`	Unmute the audio output (without changing current volume value)
`AG_ACTION_PLAYPLAYABLE`	Play an Audiogum playable (id passed in `string_param`), optionally including a start_index passed in `int_param`
`AG_ACTION_REFRESHPLAYABLE`	Refresh local playable data (id passed in `string_param`) using the start_index passed in `int_param`. Playback should not be interrupted and the next item played should be from new data
`AG_ACTION_SETPRESET`	Add a playable (id passed in `string_param`) to preset number passed in `int_param`
`AG_ACTION_PLAYPRESET`	Switch playback to a specified store preset
`AG_ACTION_PLAYSOURCE`	Switch playback to a specified input source specified in string_param
`AG_ACTION_GETPLAYER`	Respond with information about current player state, `ag_action->response_struct` will point to a `ag_player_state` structure
`AG_ACTION_GETDEVICEDETAILS`	Respond with information about the device, `ag_action->response_struct` will point to a `ag_device_info` structure
`AG_ACTION_GETPRESETS`	Respond with information about the device presets, `ag_action->response_struct` will point to a agdevicepresets structure

`AG_EVENT_ACTION`

Enumeration of values for the action member of the ag_event structure.

Values	Descriptions
`AG_EVENT_ACTION_UNKNOWN`	Unknown action
`AG_EVENT_ACTION_START`	The device started playing a "playable" (i.e. a playlist, album, etc.)
`AG_EVENT_ACTION_BEGIN`	The device began playing an item in a "playable"
`AG_EVENT_ACTION_MEDIA_BEGIN`	The device successfully started media playback
`AG_EVENT_ACTION_MEDIA_ERROR`	The device failed to start media playback
`AG_EVENT_ACTION_STOP`	The device stopped playing an item in a "playable"
`AG_EVENT_ACTION_RESUME`	The device resumed playing an item in a "playable"
`AG_EVENT_ACTION_CONTINUE`	The device continued playback. Certain services require periodic reporting that playback is still ongoing for long playing items such as radio
`AG_EVENT_ACTION_COMPLETE`	The device completed playing an item in a "playable"
`AG_EVENT_ACTION_SKIP_NEXT`	The user skipped to the next item in a "playable"
`AG_EVENT_ACTION_SKIP_PREV`	The user skipped to the previous item in a "playable"
`AG_EVENT_ACTION_SEEK`	The user seeked through an item in a "playable"
`AG_EVENT_ACTION_SUCCESS`	Voice transcription was successful
`AG_EVENT_ACTION_FAILURE`	Voice transcription failed

`AG_EVENT_CONNECTION_TYPE`

Enumeration of values for the connection_type member of the ag_event structure.

Values	Descriptions
`AG_EVENT_CONNECTION_WAN`	The device is connected over wifi or a fixed wan network
`AG_EVENT_CONNECTION_CELLULAR`	The device is connected over a cellular network

`AG_EVENT_PLAY_SOURCE_TYPE`

Enumeration of values for the source_type member of the ag_event structure.

Values	Descriptions
`AG_EVENT_PLAY_SOURCE_TYPE_UNKNOWN`	The source is unknown
`AG_EVENT_PLAY_SOURCE_TYPE_PLAYABLE`	The source is an Audiogum 'playable'
`AG_EVENT_PLAY_SOURCE_TYPE_SPOTIFYCONNECT`	The source is Spotify Connect
`AG_EVENT_PLAY_SOURCE_TYPE_AIRPLAY`	The source is AirPlay
`AG_EVENT_PLAY_SOURCE_TYPE_BLUETOOTH`	The source is Bluetooth
`AG_EVENT_PLAY_SOURCE_TYPE_DLNA`	The source is DLNA
`AG_EVENT_PLAY_SOURCE_TYPE_USB`	The source is USB
`AG_EVENT_PLAY_SOURCE_TYPE_AUX`	The source is Aux Input

`AG_EVENT_TYPE`

Enumeration of values for the type member of the ag_event structure.

Values	Descriptions
`AG_EVENT_TYPE_UNKNOWN`	Unknown type
`AG_EVENT_TYPE_PLAY_EVENT`	The event is a play event
`AG_EVENT_TYPE_VOICE_EVENT`	The event is a voice event

`AG_EVENT_VOICE_STOPPED_BY`

Enumeration of values for the voice_stopped_by member of the ag_event structure.

Values	Descriptions
`AG_EVENT_VOICE_STOPPED_BY_UNKNOWN`	Transcription stopped by unknown source
`AG_EVENT_VOICE_STOPPED_BY_CLIENT`	Transcription stopped by client
`AG_EVENT_VOICE_STOPPED_BY_SERVER`	Transcription stopped by server
`AG_EVENT_VOICE_STOPPED_BY_USER`	Transcription stopped by user

`AG_MATCH_OPERATION`

Enumeration of values for the operation member of the ag_match_event structure.

Values	Descriptions
`AG_MATCH_OPERATION_UPDATE`	The item is new or updated
`AG_MATCH_OPERATION_DELETE`	The item has been deleted

`AG_PLAY_CAPABILITY`

Enumeration of values indicating play capabilities.

Values	Descriptions
`AG_PLAY_CAPABILITY_NONE`	No special capabilties supported
`AG_PLAY_CAPABILITY_HTTP`	Supports HTTP streaming
`AG_PLAY_CAPABILITY_HTTPS`	Supports HTTPS streaming

`AG_PLAYER_STATE`

Enumeration of values indicating player state.

Values	Descriptions
`AG_PLAYER_STATE_UNKNOWN`	Unknown state
`AG_PLAYER_STATE_IDLE`	Nothing playing
`AG_PLAYER_STATE_BUFFERING`	Loading / Buffering
`AG_PLAYER_STATE_PLAYING`	Playing
`AG_PLAYER_STATE_STOPPED`	Stopped
`AG_PLAYER_STATE_PAUSED`	Paused
`AG_PLAYER_STATE_ERROR`	Errored

`AG_SOCKET_STATE`

Enumeration of values indicating remote control websocket connection states.

Values	Descriptions
`AG_SOCKET_STATE_UNKNOWN`	Unknown state
`AG_SOCKET_STATE_INVALID_ACCESS_TOKEN`	Invalid access_token
`AG_SOCKET_STATE_INVALID_RC_TOKEN`	Invalid socket token
`AG_SOCKET_STATE_UNKNOWN_CONNECTION_ERROR`	Remote Control unknown connection error - the library will attempt to reconnect
`AG_SOCKET_STATE_SERVER_UNREACHABLE`	Audiogum Remote Control server unreachable
`AG_SOCKET_STATE_CONNECTION_DROPPED`	Connection dropped - the library will attempt to reconnect
`AG_SOCKET_STATE_CONNECTED`	Connected
`AG_SOCKET_STATE_PING_SUCCESSFUL`	Server Ping successful

`AG_VOICE_CAPABILITY`

Enumeration of values indicating voice capabilities.

Values	Descriptions
`AG_VOICE_CAPABILITY_NONE`	No special capabilties required
`AG_VOICE_CAPABILITY_CONVERSATIONAL`	Enable conversational voice mode where questions / responses pass back and forth

`AG_VOICE_STATE`

Enumeration of values indicating voice connection states.

Values	Descriptions
`AG_VOICE_STATE_UNKNOWN`	Unknown state
`AG_VOICE_STATE_INVALID_DELEGATED_TOKEN`	Invalid Delegated Speech token - a token is needed to operate on behalf of the user; the session has ended - close the microphone
`AG_VOICE_STATE_ACTIVITY_DETECTED`	Voice activity detected, keep microphone open
`AG_VOICE_STATE_ACTIVITY_PHRASE_UNDERSTOOD`	Utterence received and understood - close the microphone
`AG_VOICE_STATE_ACTION_RECEIVED`	Utterence processed and action dispatched, session has ended
`AG_VOICE_STATE_UNKNOWN_ERROR`	Unknown error occurred, session has ended - close the microphone
`AG_VOICE_STATE_NOT_UNDERSTOOD`	Utterence received but not understood, session has ended - close the microphone
`AG_VOICE_STATE_NO_PLAYLIST_POSSIBLE`	Utterence received and understood as a playlist intent, but creating a playlist was not possible (e.g. the request was too specific, or no relevant music available in the territory). Session has ended - close the microphone

Structures

`ag_action struct`

Structure containing action details

Members	Descriptions
`AG_ACTION action`	The action type
`char *string_param1`	The first string param
`int int_param1`	The first int param
`void *response_struct`	`void*` pointer to a data structure to fill when required by the action - the type will differ depending upon the action received. The `AG_ACTION` states the type that will be passed
`char *internal_response_json`	Internal response representation

`ag_device_info`

Device information structure for updating cloud-held info about a device used for the ag_update_device_info function

Members	Descriptions
`char *friendly_name`	The device friendly name
`char *serial_number`	The device serial number
`char *module_version`	The device module version
`char *local_ip`	The device local IP address
`ag_ip_location *location`	The device location obtained from the `ag_get_location_from_ip` function
`int power_level`	The current device power level percentage
`char *correlation_id`	Internal correlation id for response messages

`ag_device_preset`

Structure containing details about a preset for the AG_ACTION_GETPRESETS action

Members	Descriptions
`int preset_number`	The preset number
`int start_index`	The optional start index
`char *name`	The preset name
`char *source`	The preset source - e.g. `playable`, `spotifyconnect` - see the `source` field in analytics
`char *source_id`	The ID of the item to play - e.g. could be a playable ID or a Spotify URI
`char *source_service`	The optional source service for non-audiogum presets

`ag_device_presets`

Structure containing details about presets for the AG_ACTION_GETPRESETS action

Members	Descriptions
`int num_presets`	The number of presets
`ag_device_preset *presets`	The preset details
`char *correlation_id`	Internal correlation id for response messages

`ag_event`

Structure containing an analytics event

Members	Descriptions
`AG_EVENT_TYPE type`	The event type - see `AG_EVENT_TYPE`
`AG_EVENT_ACTION action`	The action that occurred - see `AG_EVENT_ACTION`
`AG_EVENT_PLAY_SOURCE_TYPE source_type`	The playback source type - see `AG_EVENT_PLAY_SOURCE_TYPE`
`time_t localtime`	The time the action that occurred
`int sequence`	The sequence number for the event in the current session
`AG_EVENT_CONNECTION_TYPE connection_type`	The connection type that event occurred on - see `AG_EVENT_CONNECTION_TYPE`
`int offset`	The offset time in seconds that the event
`int preset`	The preset number that the playable was started from
`char* playable_item_json`	The item JSON representation obtained from the `ag_playable_item` structure
`char *playable_json`	The playable JSON representation obtained from the `ag_playable_items` structure via the `ag_get_playable_items` or `ag_get_playable_items_from_index`
`char* source_service`	The external source service
`char* source_ref`	The external source id
`char* source_name`	The external source name
`AG_EVENT_VOICE_STOPPED_BY voice_stopped_by`	How the voice session ended - see `AG_EVENT_VOICE_STOPPED_BY`
`char *voice_session_id`	The voice session id

`ag_feedback`

Structure containing feedback details

Members	Descriptions
`char *lang_code`	The feedback language code
`char *text`	Text version of the feedback
`char *audio_url`	Url to the audio version of the feedback

`ag_firmware`

Response to check device firmware version returned by ag_check_firmware_version

Members	Descriptions
`ag_response *response`	The `ag_response` containing the HTTP response
`char *download_url`	The URL to download new firmware from (if `response->response_code == 200`)
`char *region`	The region the firmware was released for (if `response->response_code == 200`)
`char *version`	The version of the firmware released (if `response->response_code == 200`)
`char *updated`	The last-updated date of the firmware released (if `response->response_code == 200`)

`ag_ip_location`

Response to look up location by IP address returned by ag_get_location_from_ip

Members	Descriptions
`ag_response *response`	The `ag_response` containing the HTTP response
`char *ip`	The public IP address of the device
`char *city`	The resolved city
`char *area`	The resolved area
`char *country_code`	The resolved ISO 3166-2 country code
`char *country_name`	The resolved country name
`char *continent_code`	The resolved continent code
`char *continent_name`	The resolved continent name
`char *time_zone`	The resolved time zone name
`double latitude`	The resolved latitude
`double longitude`	The resolved longitude

`ag_match_item`

Structure containing details about a song to be matched to the user's local catalogue

Members	Descriptions
`AG_MATCH_OPERATION operation`	The match operation - see `AG_MATCH_OPERATION`
`char* source_name`	The name of the source being scanned
`char* location`	The location of the item - a locally addressable file location - up to clients to format in a way that firmware can understand. Examples are: `/mnt/music/file.mp3` or `smb://server/share/music/file.mp3`
`char* name`	The name of the item
`char* artist_display_name`	The artist name for the item
`time_t last_modified`	The last modified time for the item
`char* album_name`	Optional album name for the item
`char* genre_name`	Optional genre name for the item
`int duration`	Optional duration in seconds of the item
`int track_number`	Optional track number

`ag_playable_item`

Structure containing details about an item that can be played

Members	Descriptions
`char *id`	The ID of the item
`char *type`	The type of the item - typically a song or audiobook
`int index`	The index type of the item in the playlist or album
`char *name`	The name of the item
`char *artist_display_name`	The artist name for the item
`char *album_name`	The album name for the item
`int duration`	The duration of the item
`int offset`	Optional offset into the item that playback should start - used for podcasts and audiobooks
`char *service`	The service the item is being played from
`char *ref`	The service ID of the item
`char *playback_protocol`	The protocol required to play the item
`char *playback_codec`	The codec required to play the item
`char *quality`	The quality of the item where available
`char *stream_url`	The stream url of the item (for non-SDK protocol services)
`time_t stream_url_expiry`	The expiry time of the stream url where appropriate
`bool controls.skip_next`	Whether skip next is allowed
`bool controls.skip_prev`	Whether skip previous is allowed
`bool continuous`	Whether this item is a continuous stream such as radio
`char *raw_json`	A JSON representation of the item to return to companion apps to display now-playing information

`ag_playable_items`

Structure containing details about the playable including items to play

Members	Descriptions
`ag_response *response`	The `ag_response` containing the HTTP response
`char *id`	The ID of the playable
`char *type`	The type of the playable
`char *userid`	The userid who created the playable
`char *name`	The name of the playable
`int start_index`	The start index used for this set of items
`int items_per_page`	The number of items requested
`int total`	The total number of items available in this playable - for internetradio, this will be 1; for dynamic playlists this field will not be returned.
`int num_items`	The number of items returned
`ag_playable_item *items`	The items to play
`int num_services`	The number of service used to play this playable
`ag_service_auth *services`	The service details
`char *analytics_json`	A JSON representation of the playable details for tracking in analytics events - pass this value to the `ag_populate_play_event` function

`ag_player_state struct`

Structure containing player state to respond to the AG_ACTION_GETPLAYER action

Members	Descriptions
`AG_PLAYER_STATE state`	The player state - see `AG_PLAYER_STATE`
`char *player_source`	The source of the playback, if appropriate
`char *playable_json`	The playable JSON representation obtained from the `ag_playable_items` structure via the `ag_get_playable_items` or `ag_get_playable_items_from_index`
`char *playable_item_json`	The Audiogum playable item being played JSON representation obtained from the `ag_playable_item` structure, if appropriate
`int offset`	The offset time in seconds in the current item if appropriate
`int preset`	The preset number that the playable was started from
`int volume`	The current volume
`bool is_mute`	Whether the player is muted
`char *correlation_id`	Internal correlation id for response messages

`ag_response`

Generic API response structure, used when there is no specific or detailed response to a function

Members	Descriptions
`int response_code`	The HTTP response_code returned by the API call. If no `access_token` is available, this will be 0.
`char *response_error`	The text error returned by the API call (if appropriate)

`ag_service_auth`

Structure containing service auth details - for services that require a local SDK to play

Members	Descriptions
`char *service_id`	The service id
`char *client_id`	The client_id to use with the service
`char *access_token`	The access_token to use with the service
`time_t access_token_expiry`	The time that the access_token to use with the service expires
`char *playback_protocol`	The playback protocol the service uses - see the `requires` part of playback requirements
`bool send_analytics`	Whether the service mandates sending playback analytics - see the `sendanalytics` part of playback requirements
`int send_continuation_event`	Whether the service mandates sending 'continue' playback analytics events after the number of seconds specified have elapsed since the last event was sent - see the `sendcontinuationevent` part of playback requirements
`bool send_media_events`	Whether the service mandates sending of 'mediabegin' and 'mediaerror' playback analytics events - see the `sendmediaevents` part of playback requirements