SMPEG(3)

NAME
smpeg - MPEG-1 audio/video playback library

SYNOPSIS

    #include <smpeg.h>

DESCRIPTION
The smpeg library provides audio/video playback of MPEG-1 data.

INITIALIZATION
SMPEG * SMPEG_new(const char *file, SMPEG_Info *info, int sdl_audio)

SMPEG * SMPEG_new_descr(int fd, SMPEG_Info *info, int sdl_audio)

SMPEG * SMPEG_new_data(void *data, SMPEG_Info *info, int sdl_audio)

void SMPEG_getinfo(SMPEG *mpeg, SMPEG_Info *info)

void SMPEG_enableaudio(SMPEG *mpeg, int enable)

void SMPEG_enablevideo(SMPEG *mpeg, int enable)

void SMPEG_delete(SMPEG *mpeg)

char * SMPEG_error(SMPEG *mpeg)

The SMPEG_new(), SMPEG_new_descr(), SMPEG_new_data() and SMPEG_new_rwops() functions read MPEG data from a file, a file descriptor, memory or a SDL_Rwops structure, respectively. A newly allocated SMPEG object is returned. If sdl_audio is non-zero, the SDL audio subsystem is used to play audio. If info is not NULL, it is filled with the following information:

    typedef struct _SMPEG_Info {
    	int	has_audio, has_video;	/* Available data */
    	int	width, height;		/* Video geometry */
    	int	current_frame;		/* Video frame# */
    	double	current_fps;		/* Frames/second */
    	char	audio_string[80];
    	int	audio_current_frame;	/* Audio playback status */
    	Uint32	current_offset;		/* Position in video */
    	Uint32	total_size;		/* Video size */
    	double	current_time;
    	double	total_time;
    } SMPEG_Info;

The SMPEG_getinfo() function returns information about mpeg in info.

The SMPEG_enableaudio() and SMPEG_enablevideo() functions toggle audio and video playback respectively.

The SMPEG_delete() function frees resources allocated by mpeg. The SMPEG_error() function returns an error string if a fatal error occured, NULL otherwise.

PLAYBACK
SMPEGstatus SMPEG_status(SMPEG *mpeg)

void SMPEG_setvolume(SMPEG *mpeg, int volume)

void SMPEG_setdisplay(SMPEG *mpeg, SDL_Surface *dst, SDL_mutex *surfLock, SMPEG_DisplayCallback callback)

void SMPEG_loop(SMPEG *mpeg, int repeat)

void SMPEG_scaleXY(SMPEG *mpeg, int width, int height)

void SMPEG_scale(SMPEG *mpeg, int scale)

void SMPEG_move(SMPEG *mpeg, int x, int y)

void SMPEG_setdisplayregion(SMPEG *mpeg, int x, int y, int w, int h)

void SMPEG_play(SMPEG *mpeg)

void SMPEG_pause(SMPEG *mpeg)

void SMPEG_stop(SMPEG *mpeg)

void SMPEG_rewind(SMPEG *mpeg)

void SMPEG_seek(SMPEG *mpeg, int nbytes)

void SMPEG_skip(SMPEG *mpeg, float seconds)

void SMPEG_renderFrame(SMPEG *mpeg, int framenum)

void SMPEG_renderFinal(SMPEG *mpeg, SDL_Surface *dst, int x, int y)

The SMPEG_status() function returns playback status:

    typedef enum {
        SMPEG_ERROR = -1,
        SMPEG_STOPPED,
        SMPEG_PLAYING
    } SMPEGstatus;

The SMPEG_setvolume() function sets the audio volume of mpeg, in the in the range 0-100. The SMPEG_setdisplay() function sets the destination surface for MPEG video playback to dst. The surfLock mutex, if not NULL, will be used to serialize access to dst. The callback function is called when an area of dst needs to be updated, its prototype matches SDL_UpdateRect(3).

The SMPEG_loop() function causes the video to loop.

The SMPEG_scaleXY() and SMPEG_scale() functions scale the pixel display to width by height pixels or scale % respectively. The SMPEG_move() function moves the video display area within dst. The SMPEG_setdisplayregion() function selects the region of the video to be shown.

The SMPEG_play() function plays mpeg. SMPEG_pause() pauses the playback. SMPEG_stop() stops the playback. SMPEG_rewind() rewinds the play position to the beginning of the MPEG data. SMPEG_seek() seeks bytes in the MPEG stream. The SMPEG_skip() function skips seconds in the MPEG stream.

The SMPEG_renderFrame() renders the frame framenum, at the current video position, which may be set using SMPEG_setdisplay() and SMPEG_move(). The SMPEG_renderFinal() function renders the last frame of the MPEG video at coordinates x and y of dst surface.

VIDEO FILTERING
SMPEG_Filter * SMPEG_Filter(SMPEG *mpeg, SMPEG_Filter *filter)

The SMPEG_Filter() function selects a video filter.

AUDIO PLAYBACK
int SMPEG_playAudio(SMPEG *mpeg, Uint8 *stream, int len)

void SMPEG_playAudioSDL(void *mpeg, Uint8 *stream, int len)

int SMPEG_wantedSpec(SMPEG *mpeg, SDL_AudioSpec *wanted)

void SMPEG_actualSpec(SMPEG *mpeg, SDL_AudioSpec *spec)

SMPEG_playAudio() is the exported callback function for audio playback. stream is the buffer, and len is the amount of data to fill. The function should return the amount of bytes that were actually written, this will be the amount requested unless the MPEG audio playback is done. SMPEG_playAudioSDL() is a wrapper for SMPEG_playAudio() that can be passed to SDL and SDL_mixer.

The SMPEG_wantedSpec() function returns the best audio spec in wanted for the MPEG audio stream. SMPEG_actualSpec() informs smpeg of the actual SDL audio spec used for sound playback.

SEE ALSO
plaympeg(1), SDL_Init(3), SDL_Init_SubSystem(3)

HISTORY
The smpeg library was Loki Software's first Open Source project. It is based on UC Berkeley's mpeg_play MPEG decoder, and SPLAY, a MPEG audio decoder created by Woo-jae Jung.

AUTHORS
The smpeg library was written by Karl Robillard and Sam Lantinga, Loki Software Inc. Streaming MPEG support was contributed by Vivien Chappelier.