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


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

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


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


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


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


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


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.

ValuesDescriptions
AG_ACTION_UNKNOWNUnknown action
AG_ACTION_PLAYPlay/resume playback, if any already started
AG_ACTION_STOPStop playback
AG_ACTION_PAUSEPause playback
AG_ACTION_SKIP_NEXTSkip player to next item
AG_ACTION_SKIP_PREVSkip player to previous item
AG_ACTION_SEEKMove player to specified offset in seconds passed in int_param
AG_ACTION_REWINDRe-start current item from the beginning
AG_ACTION_VOLUMEUPIncrease volume by one increment or by specified relative value passed in int_param
AG_ACTION_VOLUMEDOWNDecrease volume by one increment or by specified relative value passed in int_param
AG_ACTION_SETVOLUMESet volume to specified value passed in int_param (assume range 0 to 100)
AG_ACTION_MUTEMute the audio output (without changing current volume value)
AG_ACTION_UNMUTEUnmute the audio output (without changing current volume value)
AG_ACTION_PLAYPLAYABLEPlay an Audiogum playable (id passed in string_param), optionally including a start_index passed in int_param
AG_ACTION_REFRESHPLAYABLERefresh 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_SETPRESETAdd a playable (id passed in string_param) to preset number passed in int_param
AG_ACTION_PLAYPRESETSwitch playback to a specified store preset
AG_ACTION_PLAYSOURCESwitch playback to a specified input source specified in string_param
AG_ACTION_GETPLAYERRespond with information about current player state, ag_action->response_struct will point to a ag_player_state structure
AG_ACTION_GETDEVICEDETAILSRespond with information about the device, ag_action->response_struct will point to a ag_device_info structure
AG_ACTION_GETPRESETSRespond 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.

ValuesDescriptions
AG_EVENT_ACTION_UNKNOWNUnknown action
AG_EVENT_ACTION_STARTThe device started playing a "playable" (i.e. a playlist, album, etc.)
AG_EVENT_ACTION_BEGINThe device began playing an item in a "playable"
AG_EVENT_ACTION_MEDIA_BEGINThe device successfully started media playback
AG_EVENT_ACTION_MEDIA_ERRORThe device failed to start media playback
AG_EVENT_ACTION_STOPThe device stopped playing an item in a "playable"
AG_EVENT_ACTION_RESUMEThe device resumed playing an item in a "playable"
AG_EVENT_ACTION_CONTINUEThe device continued playback. Certain services require periodic reporting that playback is still ongoing for long playing items such as radio
AG_EVENT_ACTION_COMPLETEThe device completed playing an item in a "playable"
AG_EVENT_ACTION_SKIP_NEXTThe user skipped to the next item in a "playable"
AG_EVENT_ACTION_SKIP_PREVThe user skipped to the previous item in a "playable"
AG_EVENT_ACTION_SEEKThe user seeked through an item in a "playable"
AG_EVENT_ACTION_SUCCESSVoice transcription was successful
AG_EVENT_ACTION_FAILUREVoice transcription failed

AG_EVENT_CONNECTION_TYPE

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

ValuesDescriptions
AG_EVENT_CONNECTION_WANThe device is connected over wifi or a fixed wan network
AG_EVENT_CONNECTION_CELLULARThe 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.

ValuesDescriptions
AG_EVENT_PLAY_SOURCE_TYPE_UNKNOWNThe source is unknown
AG_EVENT_PLAY_SOURCE_TYPE_PLAYABLEThe source is an Audiogum 'playable'
AG_EVENT_PLAY_SOURCE_TYPE_SPOTIFYCONNECTThe source is Spotify Connect
AG_EVENT_PLAY_SOURCE_TYPE_AIRPLAYThe source is AirPlay
AG_EVENT_PLAY_SOURCE_TYPE_BLUETOOTHThe source is Bluetooth
AG_EVENT_PLAY_SOURCE_TYPE_DLNAThe source is DLNA
AG_EVENT_PLAY_SOURCE_TYPE_USBThe source is USB
AG_EVENT_PLAY_SOURCE_TYPE_AUXThe source is Aux Input

AG_EVENT_TYPE

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

ValuesDescriptions
AG_EVENT_TYPE_UNKNOWNUnknown type
AG_EVENT_TYPE_PLAY_EVENTThe event is a play event
AG_EVENT_TYPE_VOICE_EVENTThe event is a voice event

AG_EVENT_VOICE_STOPPED_BY

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

ValuesDescriptions
AG_EVENT_VOICE_STOPPED_BY_UNKNOWNTranscription stopped by unknown source
AG_EVENT_VOICE_STOPPED_BY_CLIENTTranscription stopped by client
AG_EVENT_VOICE_STOPPED_BY_SERVERTranscription stopped by server
AG_EVENT_VOICE_STOPPED_BY_USERTranscription stopped by user

AG_MATCH_OPERATION

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

ValuesDescriptions
AG_MATCH_OPERATION_UPDATEThe item is new or updated
AG_MATCH_OPERATION_DELETEThe item has been deleted

AG_PLAY_CAPABILITY

Enumeration of values indicating play capabilities.

ValuesDescriptions
AG_PLAY_CAPABILITY_NONENo special capabilties supported
AG_PLAY_CAPABILITY_HTTPSupports HTTP streaming
AG_PLAY_CAPABILITY_HTTPSSupports HTTPS streaming

AG_PLAYER_STATE

Enumeration of values indicating player state.

ValuesDescriptions
AG_PLAYER_STATE_UNKNOWNUnknown state
AG_PLAYER_STATE_IDLENothing playing
AG_PLAYER_STATE_BUFFERINGLoading / Buffering
AG_PLAYER_STATE_PLAYINGPlaying
AG_PLAYER_STATE_STOPPEDStopped
AG_PLAYER_STATE_PAUSEDPaused
AG_PLAYER_STATE_ERRORErrored

AG_SOCKET_STATE

Enumeration of values indicating remote control websocket connection states.

ValuesDescriptions
AG_SOCKET_STATE_UNKNOWNUnknown state
AG_SOCKET_STATE_INVALID_ACCESS_TOKENInvalid access_token
AG_SOCKET_STATE_INVALID_RC_TOKENInvalid socket token
AG_SOCKET_STATE_UNKNOWN_CONNECTION_ERRORRemote Control unknown connection error - the library will attempt to reconnect
AG_SOCKET_STATE_SERVER_UNREACHABLEAudiogum Remote Control server unreachable
AG_SOCKET_STATE_CONNECTION_DROPPEDConnection dropped - the library will attempt to reconnect
AG_SOCKET_STATE_CONNECTEDConnected
AG_SOCKET_STATE_PING_SUCCESSFULServer Ping successful

AG_VOICE_CAPABILITY

Enumeration of values indicating voice capabilities.

ValuesDescriptions
AG_VOICE_CAPABILITY_NONENo special capabilties required
AG_VOICE_CAPABILITY_CONVERSATIONALEnable conversational voice mode where questions / responses pass back and forth

AG_VOICE_STATE

Enumeration of values indicating voice connection states.

ValuesDescriptions
AG_VOICE_STATE_UNKNOWNUnknown state
AG_VOICE_STATE_INVALID_DELEGATED_TOKENInvalid 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_DETECTEDVoice activity detected, keep microphone open
AG_VOICE_STATE_ACTIVITY_PHRASE_UNDERSTOODUtterence received and understood - close the microphone
AG_VOICE_STATE_ACTION_RECEIVEDUtterence processed and action dispatched, session has ended
AG_VOICE_STATE_UNKNOWN_ERRORUnknown error occurred, session has ended - close the microphone
AG_VOICE_STATE_NOT_UNDERSTOODUtterence received but not understood, session has ended - close the microphone
AG_VOICE_STATE_NO_PLAYLIST_POSSIBLEUtterence 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

MembersDescriptions
AG_ACTION actionThe action type
char *string_param1The first string param
int int_param1The first int param
void *response_structvoid* 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_jsonInternal response representation

ag_device_info

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

MembersDescriptions
char *friendly_nameThe device friendly name
char *serial_numberThe device serial number
char *module_versionThe device module version
char *local_ipThe device local IP address
ag_ip_location *locationThe device location obtained from the ag_get_location_from_ip function
int power_levelThe current device power level percentage
char *correlation_idInternal correlation id for response messages

ag_device_preset

Structure containing details about a preset for the AG_ACTION_GETPRESETS action

MembersDescriptions
int preset_numberThe preset number
int start_indexThe optional start index
char *nameThe preset name
char *sourceThe preset source - e.g. playable, spotifyconnect - see the source field in analytics
char *source_idThe ID of the item to play - e.g. could be a playable ID or a Spotify URI
char *source_serviceThe optional source service for non-audiogum presets

ag_device_presets

Structure containing details about presets for the AG_ACTION_GETPRESETS action

MembersDescriptions
int num_presetsThe number of presets
ag_device_preset *presetsThe preset details
char *correlation_idInternal correlation id for response messages

ag_event

Structure containing an analytics event

MembersDescriptions
AG_EVENT_TYPE typeThe event type - see AG_EVENT_TYPE
AG_EVENT_ACTION actionThe action that occurred - see AG_EVENT_ACTION
AG_EVENT_PLAY_SOURCE_TYPE source_typeThe playback source type - see AG_EVENT_PLAY_SOURCE_TYPE
time_t localtimeThe time the action that occurred
int sequenceThe sequence number for the event in the current session
AG_EVENT_CONNECTION_TYPE connection_typeThe connection type that event occurred on - see AG_EVENT_CONNECTION_TYPE
int offsetThe offset time in seconds that the event
int presetThe preset number that the playable was started from
char* playable_item_jsonThe item JSON representation obtained from the ag_playable_item structure
char *playable_jsonThe 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_serviceThe external source service
char* source_refThe external source id
char* source_nameThe external source name
AG_EVENT_VOICE_STOPPED_BY voice_stopped_byHow the voice session ended - see AG_EVENT_VOICE_STOPPED_BY
char *voice_session_idThe voice session id

ag_feedback

Structure containing feedback details

MembersDescriptions
char *lang_codeThe feedback language code
char *textText version of the feedback
char *audio_urlUrl to the audio version of the feedback

ag_firmware

Response to check device firmware version returned by ag_check_firmware_version

MembersDescriptions
ag_response *responseThe ag_response containing the HTTP response
char *download_urlThe URL to download new firmware from (if response->response_code == 200)
char *regionThe region the firmware was released for (if response->response_code == 200)
char *versionThe version of the firmware released (if response->response_code == 200)
char *updatedThe 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

MembersDescriptions
ag_response *responseThe ag_response containing the HTTP response
char *ipThe public IP address of the device
char *cityThe resolved city
char *areaThe resolved area
char *country_codeThe resolved ISO 3166-2 country code
char *country_nameThe resolved country name
char *continent_codeThe resolved continent code
char *continent_nameThe resolved continent name
char *time_zoneThe resolved time zone name
double latitudeThe resolved latitude
double longitudeThe resolved longitude

ag_match_item

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

MembersDescriptions
AG_MATCH_OPERATION operationThe match operation - see AG_MATCH_OPERATION
char* source_nameThe name of the source being scanned
char* locationThe 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* nameThe name of the item
char* artist_display_nameThe artist name for the item
time_t last_modifiedThe last modified time for the item
char* album_nameOptional album name for the item
char* genre_nameOptional genre name for the item
int durationOptional duration in seconds of the item
int track_numberOptional track number

ag_playable_item

Structure containing details about an item that can be played

MembersDescriptions
char *idThe ID of the item
char *typeThe type of the item - typically a song or audiobook
int indexThe index type of the item in the playlist or album
char *nameThe name of the item
char *artist_display_nameThe artist name for the item
char *album_nameThe album name for the item
int durationThe duration of the item
int offsetOptional offset into the item that playback should start - used for podcasts and audiobooks
char *serviceThe service the item is being played from
char *refThe service ID of the item
char *playback_protocolThe protocol required to play the item
char *playback_codecThe codec required to play the item
char *qualityThe quality of the item where available
char *stream_urlThe stream url of the item (for non-SDK protocol services)
time_t stream_url_expiryThe expiry time of the stream url where appropriate
bool controls.skip_nextWhether skip next is allowed
bool controls.skip_prevWhether skip previous is allowed
bool continuousWhether this item is a continuous stream such as radio
char *raw_jsonA 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

MembersDescriptions
ag_response *responseThe ag_response containing the HTTP response
char *idThe ID of the playable
char *typeThe type of the playable
char *useridThe userid who created the playable
char *nameThe name of the playable
int start_indexThe start index used for this set of items
int items_per_pageThe number of items requested
int totalThe 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_itemsThe number of items returned
ag_playable_item *itemsThe items to play
int num_servicesThe number of service used to play this playable
ag_service_auth *servicesThe service details
char *analytics_jsonA 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

MembersDescriptions
AG_PLAYER_STATE stateThe player state - see AG_PLAYER_STATE
char *player_sourceThe source of the playback, if appropriate
char *playable_jsonThe 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_jsonThe Audiogum playable item being played JSON representation obtained from the ag_playable_item structure, if appropriate
int offsetThe offset time in seconds in the current item if appropriate
int presetThe preset number that the playable was started from
int volumeThe current volume
bool is_muteWhether the player is muted
char *correlation_idInternal correlation id for response messages

ag_response

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

MembersDescriptions
int response_codeThe HTTP response_code returned by the API call. If no access_token is available, this will be 0.
char *response_errorThe 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

MembersDescriptions
char *service_idThe service id
char *client_idThe client_id to use with the service
char *access_tokenThe access_token to use with the service
time_t access_token_expiryThe time that the access_token to use with the service expires
char *playback_protocolThe playback protocol the service uses - see the requires part of playback requirements
bool send_analyticsWhether the service mandates sending playback analytics - see the sendanalytics part of playback requirements
int send_continuation_eventWhether 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_eventsWhether the service mandates sending of 'mediabegin' and 'mediaerror' playback analytics events - see the sendmediaevents part of playback requirements