liboggplay 0.3.0
Typedefs | Functions
oggplay.h File Reference

The liboggplay C API. More...

#include <oggplay/oggplay_enums.h>
#include <oggplay/oggplay_reader.h>
#include <oggplay/oggplay_query.h>
#include <oggplay/oggplay_callback_info.h>
#include <oggplay/oggplay_tools.h>
#include <oggplay/oggplay_seek.h>

Go to the source code of this file.

Typedefs

typedef struct OggPlay_ OggPlay
 This is returned by oggplay_open_with_reader() or oggplay_new_with_reader().
 
typedef struct OggPlayCallbackInfo_ OggPlayCallbackInfo
 A structure for storing the decoded frames for the various streams in the Ogg container.
 
typedef int() OggPlayDataCallback(OggPlay *player, int num_records, OggPlayCallbackInfo **records, void *user)
 This is the signature of a callback which you must provide for OggPlay to call whenever there's any unpresented decoded frame available. More...
 

Functions

OggPlayoggplay_open_with_reader (OggPlayReader *reader)
 Create an OggPlay handle associated with the given reader. More...
 
OggPlayoggplay_new_with_reader (OggPlayReader *reader)
 Create a new OggPlay handle associated with the given reader. More...
 
OggPlayErrorCode oggplay_initialise (OggPlay *me, int block)
 Initialise the OggPlay handle. More...
 
OggPlayErrorCode oggplay_set_data_callback (OggPlay *me, OggPlayDataCallback callback, void *user)
 Sets a user defined OggPlayDataCallback function for the OggPlay handle. More...
 
OggPlayErrorCode oggplay_set_callback_num_frames (OggPlay *me, int stream, int frames)
 
OggPlayErrorCode oggplay_set_callback_period (OggPlay *me, int stream, int milliseconds)
 
OggPlayErrorCode oggplay_set_offset (OggPlay *me, int track, ogg_int64_t offset)
 
OggPlayErrorCode oggplay_get_video_y_size (OggPlay *me, int track, int *y_width, int *y_height)
 Get the given video track's Y-plane's width and height. More...
 
OggPlayErrorCode oggplay_get_video_uv_size (OggPlay *me, int track, int *uv_width, int *uv_height)
 Get the given video track's UV-plane's width and height. More...
 
OggPlayErrorCode oggplay_get_audio_channels (OggPlay *me, int track, int *channels)
 Get the number of channels of the audio track. More...
 
OggPlayErrorCode oggplay_get_audio_samplerate (OggPlay *me, int track, int *samplerate)
 Get the sample rate of the of the audio track. More...
 
OggPlayErrorCode oggplay_get_video_fps (OggPlay *me, int track, int *fps_denom, int *fps_num)
 Get the frame-per-second value the of a given video track. More...
 
OggPlayErrorCode oggplay_get_video_aspect_ratio (OggPlay *me, int track, int *aspect_denom, int *aspect_num)
 
OggPlayErrorCode oggplay_convert_video_to_rgb (OggPlay *me, int track, int convert, int swap_rgb)
 
OggPlayErrorCode oggplay_get_kate_category (OggPlay *me, int track, const char **category)
 
OggPlayErrorCode oggplay_get_kate_language (OggPlay *me, int track, const char **language)
 
OggPlayErrorCode oggplay_set_kate_tiger_rendering (OggPlay *me, int track, int use_tiger, int swap_rgb, int default_width, int default_height)
 
OggPlayErrorCode oggplay_overlay_kate_track_on_video (OggPlay *me, int kate_track, int video_track)
 
OggPlayErrorCode oggplay_start_decoding (OggPlay *me)
 
OggPlayErrorCode oggplay_step_decoding (OggPlay *me)
 Decode the streams in the Ogg container until we find data that hasn't been presented, yet. More...
 
OggPlayErrorCode oggplay_use_buffer (OggPlay *player, int size)
 Use the built-in OggPlayBuffer for buffering the decoded frames. More...
 
OggPlayCallbackInfo ** oggplay_buffer_retrieve_next (OggPlay *player)
 Retrive the next element in the buffer. More...
 
OggPlayErrorCode oggplay_buffer_release (OggPlay *player, OggPlayCallbackInfo **track_info)
 Release the given buffer item. More...
 
void oggplay_prepare_for_close (OggPlay *me)
 
OggPlayErrorCode oggplay_close (OggPlay *player)
 Destroys the OggPlay handle along with the associated OggPlayReader and clears out the buffer and shuts down the callback function. More...
 
int oggplay_get_available (OggPlay *player)
 
ogg_int64_t oggplay_get_duration (OggPlay *player)
 Get the duration of the Ogg content. More...
 
int oggplay_media_finished_retrieving (OggPlay *player)
 

Detailed Description

The liboggplay C API.

Authors
Shane Stephens shane.nosp@m..ste.nosp@m.phens.nosp@m.@ann.nosp@m.odex..nosp@m.net Michael Martin Viktor Gal

Typedef Documentation

◆ OggPlayDataCallback

typedef int() OggPlayDataCallback(OggPlay *player, int num_records, OggPlayCallbackInfo **records, void *user)

This is the signature of a callback which you must provide for OggPlay to call whenever there's any unpresented decoded frame available.

See also
oggplay_step_decoding
Parameters
playerThe OggPlay handle
num_recordssize of the OggPlayCallbackInfo array
recordsarray of OggPlayCallbackInfo
userA generic pointer for the data the user provided earlier.
Returns
0 to continue, non-zero to instruct OggPlay to stop.

Function Documentation

◆ oggplay_buffer_release()

OggPlayErrorCode oggplay_buffer_release ( OggPlay player,
OggPlayCallbackInfo **  track_info 
)

Release the given buffer item.

After retrieving and processing one buffer item, in order to remove the given item from the queue and release the memory allocated by the buffer item one needs to call this function.

Parameters
playerOggPlay handle
track_infoOggPlayCallbackInfo array to release.
Return values
E_OGGPLAY_OKon success.
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle.

◆ oggplay_buffer_retrieve_next()

OggPlayCallbackInfo ** oggplay_buffer_retrieve_next ( OggPlay player)

Retrive the next element in the buffer.

Parameters
playerOggPlay handle
Returns
array of OggPlayCallbackInfo - one per track.
Return values
NULLif there was no available.

◆ oggplay_close()

OggPlayErrorCode oggplay_close ( OggPlay player)

Destroys the OggPlay handle along with the associated OggPlayReader and clears out the buffer and shuts down the callback function.

Parameters
playeran OggPlay handle
Return values
E_OGGPLAY_OKon success

◆ oggplay_get_audio_channels()

OggPlayErrorCode oggplay_get_audio_channels ( OggPlay me,
int  track,
int *  channels 
)

Get the number of channels of the audio track.

Parameters
meOggPlay handle
trackthe track number of the audio track
channelsthe number of channels of the given audio track.
Return values
E_OGGPLAY_OKon success.
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle
E_OGGPLAY_BAD_TRACKthe given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPEthe given track is not an audio track
E_OGGPLAY_UNINITIALISEDthe OggPlay handle is uninitalised.

◆ oggplay_get_audio_samplerate()

OggPlayErrorCode oggplay_get_audio_samplerate ( OggPlay me,
int  track,
int *  samplerate 
)

Get the sample rate of the of the audio track.

Parameters
meOggPlay handle
trackthe track number of the audio track
sampleratethe sample rate of the audio track.
Return values
E_OGGPLAY_OKon success.
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle
E_OGGPLAY_BAD_TRACKthe given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPEthe given track is not an audio track
E_OGGPLAY_UNINITIALISEDthe OggPlay handle is uninitalised.

◆ oggplay_get_duration()

ogg_int64_t oggplay_get_duration ( OggPlay player)

Get the duration of the Ogg content.

Parameters
playerOggPlay handle.
Returns
The duration of the content in milliseconds.
Return values
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle

◆ oggplay_get_video_fps()

OggPlayErrorCode oggplay_get_video_fps ( OggPlay me,
int  track,
int *  fps_denom,
int *  fps_num 
)

Get the frame-per-second value the of a given video track.

Parameters
meOggPlay handle
trackthe track number of the audio track
fps_denomthe denumerator of the FPS
fps_numthe numerator of the FPS
Return values
E_OGGPLAY_OKon success.
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle
E_OGGPLAY_BAD_TRACKthe given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPEthe given track is not an audio track
E_OGGPLAY_UNINITIALISEDthe OggPlay handle is uninitalised.

◆ oggplay_get_video_uv_size()

OggPlayErrorCode oggplay_get_video_uv_size ( OggPlay me,
int  track,
int *  uv_width,
int *  uv_height 
)

Get the given video track's UV-plane's width and height.

Parameters
meOggPlay handle
trackthe track number of the video track
uv_widththe width of the UV-plane
uv_heightthe height of the UV-plane
Return values
E_OGGPLAY_OKon success.
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle
E_OGGPLAY_BAD_TRACKthe given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPEthe given track is not an audio track
E_OGGPLAY_UNINITIALISEDthe OggPlay handle is uninitalised.

◆ oggplay_get_video_y_size()

OggPlayErrorCode oggplay_get_video_y_size ( OggPlay me,
int  track,
int *  y_width,
int *  y_height 
)

Get the given video track's Y-plane's width and height.

Parameters
meOggPlay handle
trackthe track number of the video track
y_widththe width of the Y-plane
y_heightthe height of the Y-plane
Return values
E_OGGPLAY_OKon success.
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle
E_OGGPLAY_BAD_TRACKthe given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPEthe given track is not an audio track
E_OGGPLAY_UNINITIALISEDthe OggPlay handle is uninitalised.

◆ oggplay_initialise()

OggPlayErrorCode oggplay_initialise ( OggPlay me,
int  block 
)

Initialise the OggPlay handle.

This function creates an Oggz handle and sets it's OggzIO* functions to the OggPlayReader's io_* functions. Moreover it reads the Ogg container's content until it hasn't got all the streams' headers.

Parameters
meOggPlay handle
blockpassed as the second argument to the OggPlayReader's initialise function. E.g. in case of OggPlayTCPReader block == 0 sets the socket to non-blocking mode.
Return values
E_OGGPLAY_OKon success
E_OGGPLAY_OGGZ_UNHAPPYsomething went wrong while calling oggz_io_set_* functions.
E_OGGPLAY_BAD_INPUTgot EOF or OGGZ_ERR_HOLE_IN_DATA occured.
E_OGGPLAY_OUT_OF_MEMORYran out of memory
E_OGGPLAY_BAD_OGGPLAYinvalid OggPlay handle.

◆ oggplay_new_with_reader()

OggPlay * oggplay_new_with_reader ( OggPlayReader reader)

Create a new OggPlay handle associated with the given reader.

Parameters
readerOggPlayReader handle associated with the Ogg content
Returns
A new OggPlay handle
Return values
NULLin case of error.

◆ oggplay_open_with_reader()

OggPlay * oggplay_open_with_reader ( OggPlayReader reader)

Create an OggPlay handle associated with the given reader.

This functions creates a new OggPlay handle associated with the OggPlayReader and it calls oggplay_initialise to read the header packets of the Ogg container.

Parameters
readeran OggPlayReader handle associated with the Ogg content
Returns
A new OggPlay handle
Return values
NULLin case of error.

◆ oggplay_set_data_callback()

OggPlayErrorCode oggplay_set_data_callback ( OggPlay me,
OggPlayDataCallback  callback,
void *  user 
)

Sets a user defined OggPlayDataCallback function for the OggPlay handle.

Parameters
meOggPlay handle.
callbackA custom callback function.
userArbitrary data one wishes to pass to the callback function.
Return values
E_OGGPLAY_OKon success
E_OGGPLAY_BUFFER_MODEWe are running in buffer mode, i.e. oggplay_use_buffer has been called earlier.
E_OGGPLAY_BAD_OGGPLAYInvalid OggPlay handle.

◆ oggplay_step_decoding()

OggPlayErrorCode oggplay_step_decoding ( OggPlay me)

Decode the streams in the Ogg container until we find data that hasn't been presented, yet.

Whenever there is data that hasn't been presented the OggPlayDataCallback function will be called.

Parameters
meOggPlay handle
Return values
E_OGGPLAY_OKreached the end of the stream or shutdown detected
E_OGGPLAY_CONTINUEsuccessfully decoded the frames.
E_OGGPLAY_BAD_INPUTOGGZ_ERR_HOLE_IN_DATA occured while decoding
E_OGGPLAY_UNINITIALISEDthe OggPlayDataCallback of the OggPlay handle is not set.
E_OGGPLAY_USER_INTERRUPTuser interrupted the decoding
E_OGGPLAY_OUT_OF_MEMORYran out of memory while decoding

◆ oggplay_use_buffer()

OggPlayErrorCode oggplay_use_buffer ( OggPlay player,
int  size 
)

Use the built-in OggPlayBuffer for buffering the decoded frames.

The built-in OggPlayBuffer implements a simple lock-free FIFO for storing the decoded frames.

It tries to set the OggPlay handle's OggPlayDataCallback function to it's own implementation (oggplay_buffer_callback). Thus it will fail if a user already set OggPlayDataCallback of the OggPlay handle with oggplay_set_data_callback.

One can retrive the next record in the queue by calling oggplay_buffer_retrieve_next.

Parameters
playerthe OggPlay handle
sizeThe size of the buffer, i.e. the number of records it can store
Return values
E_OGGPLAY_OKon succsess
E_OGGPLAY_BAD_OGGPLAYThe supplied OggPlay handle is not valid
E_OGGPLAY_CALLBACK_MODEThe given OggPlay handle's OggPlayDataCallback function is already set, i.e. running in callback-mode.
E_OGGPLAY_OUT_OF_MEMORYRan out of memory while trying to allocate memory for the buffer.