kitsource.h File Reference

Video/Audio source file handling. More...

#include <inttypes.h>
#include <SDL_rwops.h>
#include "kitchensink/kitconfig.h"

Go to the source code of this file.

Data Structures
struct	Kit_Source
	Audio/video source. More...
struct	Kit_SourceStreamInfo
	Information for a source stream. More...

Typedefs
typedef enum Kit_StreamType	Kit_StreamType
	Type of the stream.
typedef struct Kit_Source	Kit_Source
	Audio/video source.
typedef struct Kit_SourceStreamInfo	Kit_SourceStreamInfo
	Information for a source stream.
typedef int(*	Kit_ReadCallback) (void *userdata, uint8_t *buf, int size)
	Callback function type for reading data stream.
typedef int64_t(*	Kit_SeekCallback) (void *userdata, int64_t offset, int whence)
	Callback function type for seeking data stream.

Enumerations
enum	Kit_StreamType {   KIT_STREAMTYPE_UNKNOWN , KIT_STREAMTYPE_VIDEO , KIT_STREAMTYPE_AUDIO , KIT_STREAMTYPE_DATA ,   KIT_STREAMTYPE_SUBTITLE , KIT_STREAMTYPE_ATTACHMENT }
	Type of the stream. More...

Functions
KIT_API Kit_Source *	Kit_CreateSourceFromUrl (const char *url)
	Create a new source from a given url.
KIT_API Kit_Source *	Kit_CreateSourceFromCustom (Kit_ReadCallback read_cb, Kit_SeekCallback seek_cb, void *userdata)
	Create a new source from custom data.
KIT_API Kit_Source *	Kit_CreateSourceFromRW (SDL_RWops *rw_ops)
	Create a new source from SDL RWops struct.
KIT_API void	Kit_CloseSource (Kit_Source *src)
	Closes a previously initialized source.
KIT_API int	Kit_GetSourceStreamInfo (const Kit_Source *src, Kit_SourceStreamInfo *info, int index)
	Fetches stream information for a given stream index.
KIT_API int	Kit_GetSourceStreamCount (const Kit_Source *src)
	Gets the amount of streams in source.
KIT_API int	Kit_GetBestSourceStream (const Kit_Source *src, const Kit_StreamType type)
	Gets the best stream index for a given stream type.

Detailed Description

Video/Audio source file handling.

Author

Tuomas Virtanen

Date

2018-06-27

Typedef Documentation

Kit_ReadCallback

typedef int(* Kit_ReadCallback) (void *userdata, uint8_t *buf, int size)

Callback function type for reading data stream.

Used by Kit_CreateSourceFromCustom() for reading data from user defined source.

A custom reader function must accept three arguments:

• userdata, this is the same data as set as last argument for Kit_CreateSourceFromCustom
• buf, a buffer the data must be copied into
• size, how much data you are expected to provide at maximum.

The function must return the amount of bytes copied to the buffer or <0 on error.

Note that this callback is passed directly to ffmpeg avio, so please refer to ffmpeg documentation for any further details.

Kit_SeekCallback

typedef int64_t(* Kit_SeekCallback) (void *userdata, int64_t offset, int whence)

Callback function type for seeking data stream.

Used by Kit_CreateSourceFromCustom() for seeking a user defined source.

A custom seeking function must accept three arguments:

• userdata, this is the same data as set as last argument for Kit_CreateSourceFromCustom
• offset, an seeking offset in bytes
• whence, reference position for the offset.

Whence parameter can be one of the standard fseek values or optionally AVSEEK_SIZE.

• SEEK_SET: Reference position is beginning of file
• SEEK_CUR: Reference position is the current position of the file pointer
• SEEK_END: Reference position is the end of the file
• AVSEEK_SIZE: Optional. Does not seek, instead finds the size of the source file.
• AVSEEK_FORCE: Optional. Suggests that seeking should be done at any cost. May be passed alongside any of the SEEK_* flags, eg. SEEK_SET|AVSEEK_FORCE.

The function must return the position (in bytes) we seeked to or <0 on error or on unsupported operation.

Note that this callback is passed directly to ffmpeg avio, so please refer to ffmpeg documentation for any further details.

Kit_Source

typedef struct Kit_Source Kit_Source

Audio/video source.

Should be created using Kit_CreateSourceFromUrl() or Kit_CreateSourceFromCustom(), and closed with Kit_CloseSource().

Source must exist for the whole duration of using a player. You must take care of closing the source yourself after you are done with it!

Kit_SourceStreamInfo

typedef struct Kit_SourceStreamInfo Kit_SourceStreamInfo

Information for a source stream.

Fetch information by using Kit_GetSourceStreamInfo().

Kit_StreamType

typedef enum Kit_StreamType Kit_StreamType

Type of the stream.

This is used by Kit_SourceStreamInfo and Kit_GetSourceStreamInfo().

Enumeration Type Documentation

Kit_StreamType

enum Kit_StreamType

Type of the stream.

This is used by Kit_SourceStreamInfo and Kit_GetSourceStreamInfo().

Enumerator
KIT_STREAMTYPE_UNKNOWN	Unknown stream type.
KIT_STREAMTYPE_VIDEO	Video stream.
KIT_STREAMTYPE_AUDIO	Audio stream.
KIT_STREAMTYPE_DATA	Data stream.
KIT_STREAMTYPE_SUBTITLE	Subtitle stream.
KIT_STREAMTYPE_ATTACHMENT	Attachment stream (images, etc)

Function Documentation

Kit_CloseSource()

KIT_API void Kit_CloseSource

(

Kit_Source *

src

)

Closes a previously initialized source.

Closes a Kit_Source that was previously created by Kit_CreateSourceFromUrl() or Kit_CreateSourceFromCustom() and frees up all memory and resources used by it. Using the source for anything after this will lead to undefined behaviour.

Passing NULL as argument is valid, and will do nothing.

Parameters

src	Previously initialized Kit_Source to close

Kit_CreateSourceFromCustom()

KIT_API Kit_Source * Kit_CreateSourceFromCustom	(	Kit_ReadCallback	read_cb,
		Kit_SeekCallback	seek_cb,
		void *	userdata
	)

Create a new source from custom data.

This can be used to load data from any resource via the given read and seek functions.

This function will return an initialized Kit_Source on success. Note that you need to manually free the source when it's no longer needed by calling Kit_CloseSource().

On failure, this function will return NULL, and further error data is available via Kit_GetError().

For example:

Kit_Source *src = Kit_CreateSourceFromCustom(read_fn, seek_fn, fp);
if(src == NULL) {
    fprintf(stderr, "Error: %s\n", Kit_GetError());
    return 1;
}

Parameters

read_cb	Read function callback
seek_cb	Seek function callback
userdata	Any data (or NULL). Will be passed to read_cb and/or seek_cb functions as-is.

Returns

Returns an initialized Kit_Source* on success or NULL on failure

Kit_CreateSourceFromRW()

KIT_API Kit_Source * Kit_CreateSourceFromRW

(

SDL_RWops *

rw_ops

)

Create a new source from SDL RWops struct.

Can be used to read data from SDL compatible sources.

This function will return an initialized Kit_Source on success. Note that you need to manually free the source when it's no longer needed by calling Kit_CloseSource().

On failure, this function will return NULL, and further error data is available via Kit_GetError().

Note that the RWops struct must exist during the whole lifetime of the source, and you must take care of freeing the rwops after it's no longer needed.

For example:

SDL_RWops *rw = SDL_RWFromFile("myvideo.mkv", "rb");
Kit_Source *src = Kit_CreateSourceFromRW(rw);
if(src == NULL) {
    fprintf(stderr, "Error: %s\n", Kit_GetError());
    return 1;
}

Parameters

rw_ops

Initialized RWOps

Returns

KIT_API* Kit_CreateSourceFromRW

Kit_CreateSourceFromUrl()

KIT_API Kit_Source * Kit_CreateSourceFromUrl

(

const char *

url

)

Create a new source from a given url.

This can be used to load video/audio from a file or network resource. If you wish to use network resources, make sure the library has been initialized using KIT_INIT_NETWORK flag.

This function will return an initialized Kit_Source on success. Note that you need to manually free the source when it's no longer needed by calling Kit_CloseSource().

On failure, this function will return NULL, and further error data is available via Kit_GetError().

For example:

Kit_Source *src = Kit_CreateSourceFromUrl(filename);
if(src == NULL) {
    fprintf(stderr, "Error: %s\n", Kit_GetError());
    return 1;
}

Parameters

url	File path or URL to a video/audio resource

Returns

Returns an initialized Kit_Source* on success or NULL on failure

Kit_GetBestSourceStream()

KIT_API int Kit_GetBestSourceStream	(	const Kit_Source *	src,
		const Kit_StreamType	type
	)

Gets the best stream index for a given stream type.

Find the best stream index for a given stream type, if one exists. If there is no stream for the wanted type, will return -1.

Parameters

src	Source to query from
type	Stream type

Returns

Index number on success (>=0), -1 on error.

Kit_GetSourceStreamCount()

KIT_API int Kit_GetSourceStreamCount

(

const Kit_Source *

src

)

Gets the amount of streams in source.

Parameters

src	Source to query from

Returns

Number of streams in the source

Kit_GetSourceStreamInfo()

KIT_API int Kit_GetSourceStreamInfo	(	const Kit_Source *	src,
		Kit_SourceStreamInfo *	info,
		int	index
	)

Fetches stream information for a given stream index.

Sets fields for given Kit_SourceStreamInfo with information about the stream.

For example:

Kit_SourceStreamInfo stream;
if(Kit_GetSourceStreamInfo(source, &stream, 0) == 1) {
    fprintf(stderr, "Error: %s\n", Kit_GetError());
    return 1;
}
fprintf(stderr, "Stream type: %s\n", Kit_GetKitStreamTypeString(stream.type))

Parameters

src	Source to query from
info	A previously allocated Kit_SourceStreamInfo to fill out
index	Stream index (starting from 0)

Returns

0 on success, 1 on error.