kitplayer.h File Reference

Video/audio player functions. More...

#include "kitchensink/kitsource.h"
#include "kitchensink/kitconfig.h"
#include "kitchensink/kitformat.h"
#include "kitchensink/kitcodec.h"
#include <SDL_render.h>

Go to the source code of this file.

Data Structures
struct	Kit_Player
	Player state container. More...
struct	Kit_PlayerStreamInfo
	Contains data about a stream selected for playback. More...
struct	Kit_PlayerInfo
	Contains information about the streams selected for playback. More...

Typedefs
typedef enum Kit_PlayerState	Kit_PlayerState
	Playback states.
typedef struct Kit_Player	Kit_Player
	Player state container.
typedef struct Kit_PlayerStreamInfo	Kit_PlayerStreamInfo
	Contains data about a stream selected for playback.
typedef struct Kit_PlayerInfo	Kit_PlayerInfo
	Contains information about the streams selected for playback.

Enumerations
enum	Kit_PlayerState { KIT_STOPPED = 0 , KIT_PLAYING , KIT_PAUSED , KIT_CLOSED }
	Playback states. More...

Functions
KIT_API Kit_Player *	Kit_CreatePlayer (const Kit_Source *src, int video_stream_index, int audio_stream_index, int subtitle_stream_index, int screen_w, int screen_h)
	Creates a new player from a source.
KIT_API void	Kit_ClosePlayer (Kit_Player *player)
	Close previously initialized player.
KIT_API void	Kit_SetPlayerScreenSize (Kit_Player *player, int w, int h)
	Sets the current screen size in pixels.
KIT_API int	Kit_GetPlayerVideoStream (const Kit_Player *player)
	Gets the current video stream index.
KIT_API int	Kit_GetPlayerAudioStream (const Kit_Player *player)
	Gets the current audio stream index.
KIT_API int	Kit_GetPlayerSubtitleStream (const Kit_Player *player)
	Gets the current subtitle stream index.
KIT_API int	Kit_GetPlayerVideoData (Kit_Player *player, SDL_Texture *texture)
	Fetches a new video frame from the player.
KIT_API int	Kit_GetPlayerVideoDataArea (Kit_Player *player, SDL_Texture *texture, SDL_Rect *area)
	Fetches a new video frame from the player.
KIT_API int	Kit_GetPlayerSubtitleData (Kit_Player *player, SDL_Texture *texture, SDL_Rect *sources, SDL_Rect *targets, int limit)
	Fetches subtitle data from the player.
KIT_API int	Kit_GetPlayerAudioData (Kit_Player *player, unsigned char *buffer, int length)
	Fetches audio data from the player.
KIT_API void	Kit_GetPlayerInfo (const Kit_Player *player, Kit_PlayerInfo *info)
	Fetches information about the currently selected streams.
KIT_API Kit_PlayerState	Kit_GetPlayerState (const Kit_Player *player)
	Returns the current state of the player.
KIT_API void	Kit_PlayerPlay (Kit_Player *player)
	Starts playback.
KIT_API void	Kit_PlayerStop (Kit_Player *player)
	Stops playback.
KIT_API void	Kit_PlayerPause (Kit_Player *player)
	Pauses playback.
KIT_API int	Kit_PlayerSeek (Kit_Player *player, double time)
	Seek to timestamp.
KIT_API double	Kit_GetPlayerDuration (const Kit_Player *player)
	Get the duration of the source.
KIT_API double	Kit_GetPlayerPosition (const Kit_Player *player)
	Get the current position of the playback.
KIT_API int	Kit_GetPlayerAspectRatio (const Kit_Player *player, int *num, int *den)
	Get the player aspect ratio, if playing video.

Detailed Description

Video/audio player functions.

Author

Tuomas Virtanen

Date

2018-06-27

Typedef Documentation

Kit_Player

typedef struct Kit_Player Kit_Player

Player state container.

Kit_PlayerInfo

typedef struct Kit_PlayerInfo Kit_PlayerInfo

Contains information about the streams selected for playback.

Kit_PlayerState

typedef enum Kit_PlayerState Kit_PlayerState

Playback states.

Kit_PlayerStreamInfo

typedef struct Kit_PlayerStreamInfo Kit_PlayerStreamInfo

Contains data about a stream selected for playback.

Enumeration Type Documentation

Kit_PlayerState

enum Kit_PlayerState

Playback states.

Enumerator
KIT_STOPPED	Playback stopped or has not started yet.
KIT_PLAYING	Playback started & player is actively decoding.
KIT_PAUSED	Playback paused; player is actively decoding but no new data is given out.
KIT_CLOSED	Playback is stopped and player is closing.

Function Documentation

Kit_ClosePlayer()

KIT_API void Kit_ClosePlayer

(

Kit_Player *

player

)

Close previously initialized player.

Closes a previously initialized Kit_Player instance. Note that this does NOT free the linked Kit_Source – you must free it manually.

Parameters

player

Player instance

Kit_CreatePlayer()

KIT_API Kit_Player * Kit_CreatePlayer	(	const Kit_Source *	src,
		int	video_stream_index,
		int	audio_stream_index,
		int	subtitle_stream_index,
		int	screen_w,
		int	screen_h
	)

Creates a new player from a source.

Creates a new player from the given source. The source must be previously successfully initialized by calling either Kit_CreateSourceFromUrl() or Kit_CreateSourceFromCustom(), and it must not be used by any other player. Source must stay valid during the whole playback (as in, don't close it while stuff is playing).

Screen width and height are used for subtitle positioning, scaling and rendering resolution. Ideally this should be precisely the size of your screen surface (in pixels). Higher resolution leads to higher resolution text rendering. This MUST be set precisely if you plan to use font hinting! If you don't care or don't have subtitles at all, set both to video surface size or 0.

For streams, either video and/or audio stream MUST be set! Either set the stream indexes manually, or pick them automatically by using Kit_GetBestSourceStream().

On success, this will return an initialized Kit_Player which can later be freed by Kit_ClosePlayer(). On error, NULL is returned and a more detailed error is available via Kit_GetError().

For example:

Kit_Player *player = Kit_CreatePlayer(
    src,
    Kit_GetBestSourceStream(src, KIT_STREAMTYPE_VIDEO),
    Kit_GetBestSourceStream(src, KIT_STREAMTYPE_AUDIO),
    Kit_GetBestSourceStream(src, KIT_STREAMTYPE_SUBTITLE),
    1280, 720);
if(player == NULL) {
    fprintf(stderr, "Unable to create player: %s\n", Kit_GetError());
    return 1;
}

Parameters

src	Valid video/audio source
video_stream_index	Video stream index or -1 if not wanted
audio_stream_index	Audio stream index or -1 if not wanted
subtitle_stream_index	Subtitle stream index or -1 if not wanted
screen_w	Screen width in pixels
screen_h	Screen height in pixels

Returns

Ínitialized Kit_Player or NULL

Kit_GetPlayerAspectRatio()

KIT_API int Kit_GetPlayerAspectRatio	(	const Kit_Player *	player,
		int *	num,
		int *	den
	)

Get the player aspect ratio, if playing video.

Sets numerator and denominator if it is possible to get a valid aspect ratio. If valid values were found, then 0 is returned. Otherwise 1 is returned, and num and den parameters are not changed.

Aspect ratio may change during the playback of the video. This function will attempt to first get the aspect ratio of the current frame. If that is not set, then decoder and finally demuxer data will be tried.

Parameters

player	Player instance
num	Numerator
den	Denominator

Returns

0 if got valid values, 1 otherwise.

Kit_GetPlayerAudioData()

KIT_API int Kit_GetPlayerAudioData	(	Kit_Player *	player,
		unsigned char *	buffer,
		int	length
	)

Fetches audio data from the player.

Note that the output buffer must be previously allocated.

Outputted audio data will be precisely what is described by the output format struct given by Kit_GetPlayerInfo().

This function will attempt to read the maximum allowed amount of data allowed by the length argument. It is possible however that there is not enough data available, at which point this function will read less and return value may differ from maximum allowed value. Return value 0 should be taken as a hint that there is nothing available.

This function will do nothing if player playback has not been started.

Parameters

player	Player instance
buffer	Buffer to read into
length	Maximum length of the buffer

Returns

Amount of data that was read, <0 on error.

Kit_GetPlayerAudioStream()

KIT_API int Kit_GetPlayerAudioStream

(

const Kit_Player *

player

)

Gets the current audio stream index.

Returns the current audio stream index or -1 if one is not selected.

Parameters

player

Player instance

Returns

Audio stream index or -1

Kit_GetPlayerDuration()

KIT_API double Kit_GetPlayerDuration

(

const Kit_Player *

player

)

Get the duration of the source.

Returns the duration of the source in seconds

Parameters

player

Player instance

Returns

Duration

Kit_GetPlayerInfo()

KIT_API void Kit_GetPlayerInfo	(	const Kit_Player *	player,
		Kit_PlayerInfo *	info
	)

Fetches information about the currently selected streams.

This function should be used to fetch codec information and output format data from the player before creating textures and setting up audio outputs.

Parameters

player	Player instance
info	A previously allocated Kit_PlayerInfo instance

Kit_GetPlayerPosition()

KIT_API double Kit_GetPlayerPosition

(

const Kit_Player *

player

)

Get the current position of the playback.

Returns the position of the playback in seconds

Parameters

player

Player instance

Returns

Position

Kit_GetPlayerState()

KIT_API Kit_PlayerState Kit_GetPlayerState

(

const Kit_Player *

player

)

Returns the current state of the player.

Parameters

player

Player instance

Returns

Current state of the player, see Kit_PlayerState

Kit_GetPlayerSubtitleData()

KIT_API int Kit_GetPlayerSubtitleData	(	Kit_Player *	player,
		SDL_Texture *	texture,
		SDL_Rect *	sources,
		SDL_Rect *	targets,
		int	limit
	)

Fetches subtitle data from the player.

Output texture will be used as a texture atlas for the subtitle fragments.

Note that the output texture must be previously allocated and valid. Make sure to have large enough a texture for the rendering resolution you picked! If your rendering resolution if 4k, then make sure to have texture sized 4096x4096 etc. This gives the texture room to handle the worst case subtitle textures. If your resolution is too small, this function will return value -1. At that point you can replace your current texture with a bigger one on the fly.

Note that the texture format for the atlas texture MUST be SDL_PIXELFORMAT_RGBA32 and the access flag MUST be set to SDL_TEXTUREACCESS_STATIC for correct rendering. Using any other format will lead to undefined behaviour. Also, make sure to set scaling quality to 0 or "nearest" before creating the texture – otherwise you get artifacts (see SDL_HINT_RENDER_SCALE_QUALITY).

This function will do nothing if player playback has not been started.

For example:

SDL_Rect sources[256];
SDL_Rect targets[256];
int got = Kit_GetPlayerSubtitleData(player, subtitle_tex, sources, targets, 256);
for(int i = 0; i < got; i++) {
    SDL_RenderCopy(renderer, subtitle_tex, &sources[i], &targets[i]);
}

Parameters

player	Player instance
texture	A previously allocated texture
sources	List of source rectangles to copy from
targets	List of target rectangles to render
limit	Defines the maximum size of your rectangle lists

Returns

Number of sources or <0 on error

Kit_GetPlayerSubtitleStream()

KIT_API int Kit_GetPlayerSubtitleStream

(

const Kit_Player *

player

)

Gets the current subtitle stream index.

Returns the current subtitle stream index or -1 if one is not selected.

Parameters

player

Player instance

Returns

Subtitle stream index or -1

Kit_GetPlayerVideoData()

KIT_API int Kit_GetPlayerVideoData	(	Kit_Player *	player,
		SDL_Texture *	texture
	)

Fetches a new video frame from the player.

This is the same as Kit_GetPlayerVideoDataArea() but without the area argument. Please refer to that function for description.

Kit_GetPlayerVideoDataArea()

KIT_API int Kit_GetPlayerVideoDataArea	(	Kit_Player *	player,
		SDL_Texture *	texture,
		SDL_Rect *	area
	)

Fetches a new video frame from the player.

Note that the output texture must be previously allocated and valid.

It is important to select the correct texture format and size. If you pick a different texture format or size from what the decoder outputs, then the decoder will attempt to convert the frames to fit the texture. This will slow down the decoder a lot however, so if possible, pick the texture format from what Kit_GetPlayerInfo() outputs.

Access flag for the texture MUST always be SDL_TEXTUREACCESS_STATIC! Anything else will lead to undefined behaviour.

Area argument can be given to acquire the current video frame content area. Note that this may change if you have video that changes frame size on the fly.

This function will do nothing if player playback has not been started.

Parameters

player	Player instance
texture	A previously allocated texture
area	Rendered video surface area

Returns

0 on success, 1 on error

Kit_GetPlayerVideoStream()

KIT_API int Kit_GetPlayerVideoStream

(

const Kit_Player *

player

)

Gets the current video stream index.

Returns the current video stream index or -1 if one is not selected.

Parameters

player

Player instance

Returns

Video stream index or -1

Kit_PlayerPause()

KIT_API void Kit_PlayerPause

(

Kit_Player *

player

)

Pauses playback.

State shifts:

• If player is already paused, will do nothing.
• If player is stopped, will do nothing.
• If player is started, will pause playback (and background decoding).

Parameters

player

Player instance

Kit_PlayerPlay()

KIT_API void Kit_PlayerPlay

(

Kit_Player *

player

)

Starts playback.

State shifts:

• If player is already playing, will do nothing.
• If player is paused, will resume playback.
• If player is stopped, will begin playback (and background decoding).

Parameters

player

Player instance

Kit_PlayerSeek()

KIT_API int Kit_PlayerSeek	(	Kit_Player *	player,
		double	time
	)

Seek to timestamp.

Rewinds or forwards video/audio playback to the given timestamp (in seconds).

This may not work for network or custom sources!

Parameters

player	Player instance
time	Timestamp to seek to in seconds

Returns

0 on success, 1 on failure.

Kit_PlayerStop()

KIT_API void Kit_PlayerStop

(

Kit_Player *

player

)

Stops playback.

State shifts:

• If player is already stopped, will do nothing.
• If player is paused, will stop playback.
• If player is started, will stop playback (and background decoding).

Parameters

player

Player instance

Kit_SetPlayerScreenSize()

KIT_API void Kit_SetPlayerScreenSize	(	Kit_Player *	player,
		int	w,
		int	h
	)

Sets the current screen size in pixels.

Call this to change the subtitle font rendering resolution if eg. your video window size changes.

This does nothing if subtitles are not in use or if subtitles are bitmaps.

Parameters

player	Player instance
w	New width in pixels
h	New height in pixels