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. | |
Functions | |
OggPlay * | oggplay_open_with_reader (OggPlayReader *reader) |
Create an OggPlay handle associated with the given reader. | |
OggPlay * | oggplay_new_with_reader (OggPlayReader *reader) |
Create a new OggPlay handle associated with the given reader. | |
OggPlayErrorCode | oggplay_initialise (OggPlay *me, int block) |
Initialise the OggPlay handle. | |
OggPlayErrorCode | oggplay_set_data_callback (OggPlay *me, OggPlayDataCallback callback, void *user) |
Sets a user defined OggPlayDataCallback function for the OggPlay handle. | |
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. | |
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. | |
OggPlayErrorCode | oggplay_get_audio_channels (OggPlay *me, int track, int *channels) |
Get the number of channels of the audio track. | |
OggPlayErrorCode | oggplay_get_audio_samplerate (OggPlay *me, int track, int *samplerate) |
Get the sample rate of the of the audio track. | |
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. | |
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. | |
OggPlayErrorCode | oggplay_use_buffer (OggPlay *player, int size) |
Use the built-in OggPlayBuffer for buffering the decoded frames. | |
OggPlayCallbackInfo ** | oggplay_buffer_retrieve_next (OggPlay *player) |
Retrive the next element in the buffer. | |
OggPlayErrorCode | oggplay_buffer_release (OggPlay *player, OggPlayCallbackInfo **track_info) |
Release the given buffer item. | |
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. | |
int | oggplay_get_available (OggPlay *player) |
ogg_int64_t | oggplay_get_duration (OggPlay *player) |
Get the duration of the Ogg content. | |
int | oggplay_media_finished_retrieving (OggPlay *player) |
The liboggplay C API.
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.
player | The OggPlay handle | |
num_records | size of the OggPlayCallbackInfo array | |
records | array of OggPlayCallbackInfo | |
user | A generic pointer for the data the user provided earlier. |
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.
player | OggPlay handle | |
track_info | OggPlayCallbackInfo array to release. |
E_OGGPLAY_OK | on success. | |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle. |
OggPlayCallbackInfo** oggplay_buffer_retrieve_next | ( | OggPlay * | player | ) |
Retrive the next element in the buffer.
player | OggPlay handle |
NULL | if there was no available. |
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.
player | an OggPlay handle |
E_OGGPLAY_OK | on success |
OggPlayErrorCode oggplay_get_audio_channels | ( | OggPlay * | me, | |
int | track, | |||
int * | channels | |||
) |
Get the number of channels of the audio track.
me | OggPlay handle | |
track | the track number of the audio track | |
channels | the number of channels of the given audio track. |
E_OGGPLAY_OK | on success. | |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle | |
E_OGGPLAY_BAD_TRACK | the given track number does not exists | |
E_OGGPLAY_WRONG_TRACK_TYPE | the given track is not an audio track | |
E_OGGPLAY_UNINITIALISED | the OggPlay handle is uninitalised. |
OggPlayErrorCode oggplay_get_audio_samplerate | ( | OggPlay * | me, | |
int | track, | |||
int * | samplerate | |||
) |
Get the sample rate of the of the audio track.
me | OggPlay handle | |
track | the track number of the audio track | |
samplerate | the sample rate of the audio track. |
E_OGGPLAY_OK | on success. | |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle | |
E_OGGPLAY_BAD_TRACK | the given track number does not exists | |
E_OGGPLAY_WRONG_TRACK_TYPE | the given track is not an audio track | |
E_OGGPLAY_UNINITIALISED | the OggPlay handle is uninitalised. |
ogg_int64_t oggplay_get_duration | ( | OggPlay * | player | ) |
Get the duration of the Ogg content.
player | OggPlay handle. |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle |
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.
me | OggPlay handle | |
track | the track number of the audio track | |
fps_denom | the denumerator of the FPS | |
fps_num | the numerator of the FPS |
E_OGGPLAY_OK | on success. | |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle | |
E_OGGPLAY_BAD_TRACK | the given track number does not exists | |
E_OGGPLAY_WRONG_TRACK_TYPE | the given track is not an audio track | |
E_OGGPLAY_UNINITIALISED | the OggPlay handle is uninitalised. |
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.
me | OggPlay handle | |
track | the track number of the video track | |
uv_width | the width of the UV-plane | |
uv_height | the height of the UV-plane |
E_OGGPLAY_OK | on success. | |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle | |
E_OGGPLAY_BAD_TRACK | the given track number does not exists | |
E_OGGPLAY_WRONG_TRACK_TYPE | the given track is not an audio track | |
E_OGGPLAY_UNINITIALISED | the OggPlay handle is uninitalised. |
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.
me | OggPlay handle | |
track | the track number of the video track | |
y_width | the width of the Y-plane | |
y_height | the height of the Y-plane |
E_OGGPLAY_OK | on success. | |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle | |
E_OGGPLAY_BAD_TRACK | the given track number does not exists | |
E_OGGPLAY_WRONG_TRACK_TYPE | the given track is not an audio track | |
E_OGGPLAY_UNINITIALISED | the OggPlay handle is uninitalised. |
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.
me | OggPlay handle | |
block | passed 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. |
E_OGGPLAY_OK | on success | |
E_OGGPLAY_OGGZ_UNHAPPY | something went wrong while calling oggz_io_set_* functions. | |
E_OGGPLAY_BAD_INPUT | got EOF or OGGZ_ERR_HOLE_IN_DATA occured. | |
E_OGGPLAY_OUT_OF_MEMORY | ran out of memory | |
E_OGGPLAY_BAD_OGGPLAY | invalid OggPlay handle. |
OggPlay* oggplay_new_with_reader | ( | OggPlayReader * | reader | ) |
Create a new OggPlay handle associated with the given reader.
reader | OggPlayReader handle associated with the Ogg content |
NULL | in case of error. |
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.
reader | an OggPlayReader handle associated with the Ogg content |
NULL | in case of error. |
OggPlayErrorCode oggplay_set_data_callback | ( | OggPlay * | me, | |
OggPlayDataCallback | callback, | |||
void * | user | |||
) |
Sets a user defined OggPlayDataCallback function for the OggPlay handle.
me | OggPlay handle. | |
callback | A custom callback function. | |
user | Arbitrary data one wishes to pass to the callback function. |
E_OGGPLAY_OK | on success | |
E_OGGPLAY_BUFFER_MODE | We are running in buffer mode, i.e. oggplay_use_buffer has been called earlier. | |
E_OGGPLAY_BAD_OGGPLAY | Invalid OggPlay handle. |
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.
me | OggPlay handle |
E_OGGPLAY_OK | reached the end of the stream or shutdown detected | |
E_OGGPLAY_CONTINUE | successfully decoded the frames. | |
E_OGGPLAY_BAD_INPUT | OGGZ_ERR_HOLE_IN_DATA occured while decoding | |
E_OGGPLAY_UNINITIALISED | the OggPlayDataCallback of the OggPlay handle is not set. | |
E_OGGPLAY_USER_INTERRUPT | user interrupted the decoding | |
E_OGGPLAY_OUT_OF_MEMORY | ran out of memory while decoding |
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.
player | the OggPlay handle | |
size | The size of the buffer, i.e. the number of records it can store |
E_OGGPLAY_OK | on succsess | |
E_OGGPLAY_BAD_OGGPLAY | The supplied OggPlay handle is not valid | |
E_OGGPLAY_CALLBACK_MODE | The given OggPlay handle's OggPlayDataCallback function is already set, i.e. running in callback-mode. | |
E_OGGPLAY_OUT_OF_MEMORY | Ran out of memory while trying to allocate memory for the buffer. |