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.
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)
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 up access_token
and other internal memory allocated.
void ag_free()
Get the library version number.
char *ag_get_version()
char*
containing the library version.
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()
bool
indicating whether the library has a valid access_token.
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)
expiry
The time to checkbool
indicating whether the time value has expired.
Look up device location from IP address.
ag_ip_location *ag_get_location_from_ip()
ag_ip_location
structure containing location information.
void ag_free_ip_location(ag_ip_location *location)
location
The location details to free.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)
key
The key to get config forchar*
string containing the config value, if available. Caller must free the return value.
Check for new firmware versions based on the current version.
ag_firmware *ag_check_firmware_version(const char *region)
region
The region to check for firmware in (this can be obtained with the ag_get_location_from_ip
function)ag_firmware
structure containing update information if available.
void ag_free_firmware(ag_firmware *fw)
fw
The firmware details to free.Updates the cloud details held about the device.
ag_response *ag_update_device_info(ag_device_info *info)
info
The device informationag_response
structure containing the response code and optional error from the API call.
void ag_free_response(ag_response *response)
response
The response to free.Get the next set of items to play for a playable.
ag_playable_items *ag_get_playable_items(const char *playable_id)
playable_id
The ID of the playable to fetch items forag_playable_items
structure containing details on the playable as well as items to play.
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)
playable_id
The ID of the playable to fetch items forstart_index
The start index to fetch items fromag_playable_items
structure containing details on the playable as well as items to play.
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)
playable
The playable to extract the service details fromservice
The service idag_service_auth
structure containing the service details.
void ag_free_playable_items(ag_playable_items *items)
items
The items to free. 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)
playable_id
The ID of the playable to fetch items foritem
The item to refreshchar *
containing the new stream url if the call succeeded.
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)
playable_id
The ID of the playable to fetch items forservice_id
The service to refresh auth details forag_service_auth
structure containing updated auth details.
void ag_free_service_auth(ag_service_auth *auth)
auth
The items to free.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)
event
- a pointer to a pre-allocated event structureaction
- the play action that occurred - see action typesconnection_type
- the connection type that was active when the event occurredplayable_analytics_json
- the analytics_json obtained from ag_playable_items
preset
- the preset number the playback started fromplayable_item
- the item being played (where appropriate)offset
- the offset in the item being played at which time the event occurredPopulates 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)
event
- a pointer to a pre-allocated event structureaction
- the play action that occurred - see action typesconnection_type
- the connection type that was active when the event occurredsource_type
- the playback source typesource_service
- the optional service being played fromsource_ref
- the optional ID of the container item being played - e.g. a playlist or albumsource_name
- the optional name of the container item being played - e.g. a playlist or albumpreset
- the preset number the playback started fromplayable_item
- details about the item being played (where appropriate)offset
- the offset in the item being played at which time the event occurredPopulates 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)
event
- a pointer to a pre-allocated event structureaction
- the action that occurred - see action types - in this case success or failureconnection_type
- the connection type that was active when the event occurredstopped_by
- how the audio recording was stoppedSends 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)
events
a pointer to the array of eventsnum_events
The number of events in the array to sendag_response
structure containing the response code and optional error from the API call.
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)
events
a pointer to the array of eventsnum_events
The number of events in the array to freeStarts a job for matching content for the specified user catalogue.
char *ag_match_start_job(char *catalog_id)
catalog_id
- the ID of the user catalogue to send matches tochar *
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.
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)
item
- a pointer to a pre-allocated ag_match_item
structuresource_name
- name of the source being scanned - this would be a NAS server name, a phone identifier or similarlocation
- the locally addressable location of the itemname
- the name of the itemartist_display_name
- the artist name for the itemlast_modified
- the last modified time for the itemalbum_name
- the optional album name for the itemgenre_name
- the optional genre name of the itemduration
- the optional duration in seconds of the itemtrack_number
- the optional track numberPopulates 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)
item
- a pointer to a pre-allocated ag_match_item
structuresource_name
- name of the source being scanned - this would be a NAS server name, a phone identifier or similarlocation
- the locally addressable location of the itemSends 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)
job_id
- the match job the items pertain toitems
- a pointer to the array of itemsnum_items
- the number of items in the array to sendag_response
structure containing the response code and optional error from the API call.
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)
items
a pointer to the items to freenum_events
The number of items in the array to freeInforms the Audiogum platform that the ongoing match job has completed sending metadata.
void ag_match_send_complete(char *job_id)
job_id
- the match job idStarts 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)
actions_understood
- a bit-wise combination of AG_ACTION
control actions this device understandsplay_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 sentstate_callback
- ag_socket_state_callback
function pointer to call when connection state changes occuraction_callback
- ag_action_callback
function pointer to call when actions are receivedGets the device remote control token to pass to companion apps.
char *ag_get_remotecontrol_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()
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)
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)
actions
optional array of ag_action
receivednum_actions
the number of actions receivedfeedback
optional accompanying feeback to play or display to the userexpect_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)
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)
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)
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)
message
- the json message receivedaction_callback
- function to call when actions are receivedresponse_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)
actions
- a bit-wise combination of AG_ACTION
control actions this device understandsStarts 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)
encoding
- the audio encoding - pcm
or flac
sample_rate
- the audio sample rate - e.g. 16000state_callback
- ag_voice_state_callback
function pointer to call when connection state changes occurplayer_state
- the current player info in a ag_player_state
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)
player_state
- current player infoSends raw audio data.
void ag_voice_send_mic_data(unsigned char *buffer, int length)
buffer
- the bytes to sendlength
- the number of bytes to sendSends a termination message if no silence is recorded after the user talks. See Natural Language Understanding docs.
void ag_voice_send_mic_terminator()
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)
response
- the full JSON body returned access_token obtained from the speech token API callGets whether the library has a stored delegated_token - attempts to refresh if necessary.
void ag_has_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()
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)
text
- the text transcribed by the separate ASR enginetranscription_source
- the source of the transcriptionactions_understood
- a bit-wise combination of AG_ACTION
control actions this device understandsplay_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 sentplayer_state
- the current player info in a ag_player_state
action_callback
- ag_action_callback
function pointer to call when actions are receivedAG_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)
state
- the latest AG_VOICE_STATE
text
- optional text detected - only used for AG_VOICE_STATE_ACTIVITY_PHRASE_UNDERSTOOD
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 |
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 |