#include "SG.h"

Include dependency graph for SG_Com_Player.h:

Data Structures
struct	SG_COM_PLAYER_Config
	Structure containing a Player configuration. More...

Macros
#define	SG_COM_PLAYER_VERSION_NAME "5.3.0"
	Copyright (c) 2024 Speech Graphics Ltd. More...

Typedefs
typedef struct SG_COM_PLAYER_Config	SG_COM_PLAYER_Config
	Structure containing a Player configuration. More...

typedef struct SG_COM_PLAYER_Context *	SG_COM_PLAYER_Handle
	Handle type. More...

Enumerations
enum	SG_COM_PLAYER_Error { SG_COM_PLAYER_ERROR_OK , SG_COM_PLAYER_ERROR_INVALID_HANDLE , SG_COM_PLAYER_ERROR_INVALID_PACKET , SG_COM_PLAYER_ERROR_INVALID_EVENT , SG_COM_PLAYER_ERROR_INVALID_PARAM , SG_COM_PLAYER_ERROR_OUT_OF_ORDER_PACKET_DISCARDED , SG_COM_PLAYER_ERROR_EXCEPTION , SG_COM_PLAYER_ERROR_NOT_IMPLEMENTED , SG_COM_PLAYER_ERROR_UNDEFINED }
	Enum of error codes. More...

Functions
SG_DYN const char *	SG_COM_PLAYER_GetExceptionText (void)
	Retrieve exception text after SG_COM_PLAYER_ERROR_EXCEPTION error. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_Initialize (SG_LoggingLevel logging_level, SG_LoggingCallback logging_callback)
	Initialize the internal context of SG Com. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_Shutdown (void)
	Shut down and dispose of the internal context of SG Com. More...

SG_DYN const char *	SG_COM_PLAYER_GetVersionString (void)
	Get the runtime version number for this library in string format. More...

SG_DYN unsigned int	SG_COM_PLAYER_GetVersionNumber (void)
	Get the runtime version number for this library. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_Create (const SG_COM_PLAYER_Config player_config, SG_COM_PLAYER_Handle player_handle)
	Create a Player to play the output from a Broadcast Engine. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_Destroy (SG_COM_PLAYER_Handle player_handle)
	Destroy a Player. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_ReceivePacket (SG_COM_PLAYER_Handle player_handle, const char *packet, sg_size packet_bytes)
	Receive an output packet from an Engine into the corresponding Player. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_ReceiveEvent (SG_COM_PLAYER_Handle player_handle, const char *event, sg_size event_bytes)
	Receive an event loaded in memory into the corresponding Player. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_GetAnimationNodes (SG_COM_PLAYER_Handle player_handle, SG_AnimationNode *animation_nodes, sg_size num_animation_nodes)
	Get the animation nodes for a given Player. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_UpdateAnimation (SG_COM_PLAYER_Handle player_handle, double time_ms, double *current_time_ms)
	Set the current play time and update the animation nodes. More...

SG_DYN SG_COM_PLAYER_Error	SG_COM_PLAYER_GetPlayableRange (SG_COM_PLAYER_Handle player_handle, double min_time_ms, double max_time_ms)
	Get the range of buffered animation. More...

Macro Definition Documentation

◆ SG_COM_PLAYER_VERSION_NAME

#define SG_COM_PLAYER_VERSION_NAME "5.3.0"

String representation of SG_Com_Player version Compare this definition with the output of SG_COM_PLAYER_GetVersionString() to ensure that this .h file matches the binary

Definition at line 13 of file SG_Com_Player.h.

Typedef Documentation

◆ SG_COM_PLAYER_Config

typedef struct SG_COM_PLAYER_Config SG_COM_PLAYER_Config

Structure containing a Player configuration.

◆ SG_COM_PLAYER_Handle

typedef struct SG_COM_PLAYER_Context* SG_COM_PLAYER_Handle

Handle type.

Definition at line 99 of file SG_Com_Player.h.

Enumeration Type Documentation

◆ SG_COM_PLAYER_Error

enum SG_COM_PLAYER_Error

Enum of error codes.

Enumerator
SG_COM_PLAYER_ERROR_OK	No error.
SG_COM_PLAYER_ERROR_INVALID_HANDLE	An invalid Engine or Player was created or referenced.
SG_COM_PLAYER_ERROR_INVALID_PACKET	An invalid data packet was received.
SG_COM_PLAYER_ERROR_INVALID_EVENT	An invalid event was received.
SG_COM_PLAYER_ERROR_INVALID_PARAM	An invalid parameter was passed to a function.
SG_COM_PLAYER_ERROR_OUT_OF_ORDER_PACKET_DISCARDED	A data packet was received out of order and was discarded.
SG_COM_PLAYER_ERROR_EXCEPTION	An exception was raised, call SG_COM_PLAYER_GetExceptionText() for details.
SG_COM_PLAYER_ERROR_NOT_IMPLEMENTED	This operation is not implemented.
SG_COM_PLAYER_ERROR_UNDEFINED	An unclassified error occurred.

Definition at line 22 of file SG_Com_Player.h.

Function Documentation

◆ SG_COM_PLAYER_Create()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_Create	(	const SG_COM_PLAYER_Config *	player_config,
		SG_COM_PLAYER_Handle *	player_handle
	)

Create a Player to play the output from a Broadcast Engine.

Parameters

	player_config	Pointer to an SG_COM_PLAYER_Config structure.
[out]	player_handle	Output handle to the created Player.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_PLAYER_Destroy()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_Destroy ( SG_COM_PLAYER_Handle player_handle )

Destroy a Player.

Parameters

player_handle The Player to be destroyed.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_PLAYER_GetAnimationNodes()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_GetAnimationNodes	(	SG_COM_PLAYER_Handle	player_handle,
		SG_AnimationNode **	animation_nodes,
		sg_size *	num_animation_nodes
	)

Get the animation nodes for a given Player.

Parameters

	player_handle	The Player.
[out]	animation_nodes	An array of animation nodes managed by SG Com.
[out]	num_animation_nodes	The number of animation nodes.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_PLAYER_GetExceptionText()

SG_DYN const char * SG_COM_PLAYER_GetExceptionText ( void )

Retrieve exception text after SG_COM_PLAYER_ERROR_EXCEPTION error.

Returns: Pointer to null terminated string.

◆ SG_COM_PLAYER_GetPlayableRange()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_GetPlayableRange	(	SG_COM_PLAYER_Handle	player_handle,
		double *	min_time_ms,
		double *	max_time_ms
	)

Get the range of buffered animation.

Parameters

player_handle	The Player.
min_time_ms[out]	The minimum time of the playback window in milliseconds.
max_time_ms[out]	The maximum time of the playback window in millseconds.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_PLAYER_GetVersionNumber()

SG_DYN unsigned int SG_COM_PLAYER_GetVersionNumber ( void )

Get the runtime version number for this library.

Returns: The runtime version number for this library.

The format of the returned value is vvvmmmppp where v is major version, m is minor version and p is patch version.

◆ SG_COM_PLAYER_GetVersionString()

SG_DYN const char * SG_COM_PLAYER_GetVersionString ( void )

Get the runtime version number for this library in string format.

Returns: String representation of the version of this library

The format of the retured value is "major.minor.patch-label", for example 0.1.0-alpha.

◆ SG_COM_PLAYER_Initialize()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_Initialize	(	SG_LoggingLevel	logging_level,
		SG_LoggingCallback	logging_callback
	)

Initialize the internal context of SG Com.

This must be called once at startup before using any other functions in this API.

Parameters

log_level	The logging level to set, from SG_LoggingLevel.
logging_callback	A callback that can be used for logging (pass nullptr if not used).

Returns: Error code indicating success or reason for failure.

On Windows, OSX and Linux, if you do not provide a logging callback, SG Com will log to file. Log files will be written to following directories:

Windows : C:\Users\<User Name>\AppData\Local\Speech Graphics\logs
OSX : /Users/<User Name>/Library/Application Support/Speech Graphics/logs
Linux : ~/.carnival/logs/

On all other platforms, SG_Com will not log to file. Instead, you must provide a callback to accept logging messages. Your callback is responsible for directing the message to a logging system such as the Android or iOS log, or perhaps your applications' own custom logger.

◆ SG_COM_PLAYER_ReceiveEvent()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_ReceiveEvent	(	SG_COM_PLAYER_Handle	player_handle,
		const char *	event,
		sg_size	event_bytes
	)

Receive an event loaded in memory into the corresponding Player.

Parameters

player_handle	The Player.
event	Pointer to the event data.
packet_bytes	The event size in bytes.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_PLAYER_ReceivePacket()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_ReceivePacket	(	SG_COM_PLAYER_Handle	player_handle,
		const char *	packet,
		sg_size	packet_bytes
	)

Receive an output packet from an Engine into the corresponding Player.

Parameters

player_handle	The Player.
packet	The packet.
packet_bytes	The packet size in bytes.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_PLAYER_Shutdown()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_Shutdown ( void )

Shut down and dispose of the internal context of SG Com.

This must be the last function call to SG Com.

Returns: Error code indicating success or reason for failure.

◆ SG_COM_PLAYER_UpdateAnimation()

SG_DYN SG_COM_PLAYER_Error SG_COM_PLAYER_UpdateAnimation	(	SG_COM_PLAYER_Handle	player_handle,
		double	time_ms,
		double *	current_time_ms
	)

Set the current play time and update the animation nodes.

The time value will be clamped to the playable range.

Parameters

player_handle	The Player.
time_ms	The time (in milliseconds).
current_time_ms[out]	The new current time. If range clamping occurred, this will be different from the input time. May be nullptr.

Returns: Error code.

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ SG_COM_PLAYER_VERSION_NAME

Typedef Documentation

◆ SG_COM_PLAYER_Config

◆ SG_COM_PLAYER_Handle

Enumeration Type Documentation

◆ SG_COM_PLAYER_Error

Function Documentation

◆ SG_COM_PLAYER_Create()

◆ SG_COM_PLAYER_Destroy()

◆ SG_COM_PLAYER_GetAnimationNodes()

◆ SG_COM_PLAYER_GetExceptionText()

◆ SG_COM_PLAYER_GetPlayableRange()

◆ SG_COM_PLAYER_GetVersionNumber()

◆ SG_COM_PLAYER_GetVersionString()

◆ SG_COM_PLAYER_Initialize()

◆ SG_COM_PLAYER_ReceiveEvent()

◆ SG_COM_PLAYER_ReceivePacket()

◆ SG_COM_PLAYER_Shutdown()

◆ SG_COM_PLAYER_UpdateAnimation()