Player

High-level, reusable control layer over a pipeline. More...

Files
file	mpipe_player.h
	Media-player-like control layer for a pipeline.

Data Structures
struct	mpipe_player
	Player instance. More...

Functions
int	mpipe_player_init (struct mpipe_player *player, struct mpipe *pipeline)
	Initialize a player and start its worker thread.
int	mpipe_player_play (struct mpipe_player *player)
	Request PLAYING.
int	mpipe_player_pause (struct mpipe_player *player)
	Request PAUSED.
int	mpipe_player_toggle (struct mpipe_player *player)
	Toggle between PLAYING and PAUSED.
int	mpipe_player_stop (struct mpipe_player *player)
	Request READY.
int	mpipe_player_replay (struct mpipe_player *player)
	Restart playback from the beginning.
int	mpipe_player_quit (struct mpipe_player *player)
	Ask the worker to stop the pipeline and exit.
int	mpipe_player_wait_quit (struct mpipe_player *player)
	Block until the player worker exits.
int	mpipe_player_deinit (struct mpipe_player *player)
	Wait for the worker to exit and release the player's resources.

Detailed Description

High-level, reusable control layer over a pipeline.

The player is a thin helper that owns the run-time lifecycle of a pipeline: play, pause, stop, replay and quit.

All state transitions are serialized on a dedicated worker thread so that:

• the caller (e.g. an interactive console loop) never blocks on a pipeline teardown, and
• end-of-stream / error notifications coming from a pipeline thread never trigger a state change in that same thread's context (which would attempt to join the thread that is running it).

The caller enqueues commands with the mpipe_player_*() API; the worker applies them one at a time.

Function Documentation

mpipe_player_deinit()

int mpipe_player_deinit

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Wait for the worker to exit and release the player's resources.

If the worker has not been asked to quit yet, this requests it first. After this call the player must be re-initialized before reuse.

Parameters

player

Player initialized with mpipe_player_init.

Return values

0

Success.

mpipe_player_init()

int mpipe_player_init	(	struct mpipe_player *	player,
		struct mpipe *	pipeline )

#include <mpipe_player.h>

Initialize a player and start its worker thread.

Registers a bus listener that auto-stops the pipeline on end-of-stream or error. The pipeline must already be built and linked, but should be in the READY state (not yet playing).

Note

Only a single player instance can be active at a time.

Parameters

player	Pointer to an uninitialized Player.
pipeline	Pointer to the pipeline to control.

Return values

0	Success.
-EBUSY	Another player instance is already active.
-EIO	The bus observer could not be attached.

mpipe_player_pause()

int mpipe_player_pause

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Request PAUSED.

Suspends streaming while preserving queued data. No effect unless PLAYING.

Parameters

player

Player initialized with mpipe_player_init.

Returns

0 on success, negative errno on failure.

mpipe_player_play()

int mpipe_player_play

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Request PLAYING.

From READY this starts the pipeline; from PAUSED it resumes without data loss. No effect if already PLAYING.

Parameters

player

Player initialized with mpipe_player_init.

Returns

0 on success, negative errno on failure.

mpipe_player_quit()

int mpipe_player_quit

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Ask the worker to stop the pipeline and exit.

Returns immediately; use mpipe_player_deinit to wait for the worker to finish and release its resources.

Parameters

player

Player initialized with mpipe_player_init.

Returns

0 on success, negative errno on failure.

mpipe_player_replay()

int mpipe_player_replay

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Restart playback from the beginning.

Equivalent to a stop followed by a play.

Parameters

player

Player initialized with mpipe_player_init.

Returns

0 on success, negative errno on failure.

mpipe_player_stop()

int mpipe_player_stop

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Request READY.

Flushes any queued data and joins all streaming threads.

Parameters

player

Player initialized with mpipe_player_init.

Returns

0 on success, negative errno on failure.

mpipe_player_toggle()

int mpipe_player_toggle

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Toggle between PLAYING and PAUSED.

If PLAYING, pauses; otherwise plays (resuming from PAUSED or starting from READY).

Parameters

player

Player initialized with mpipe_player_init.

Returns

0 on success, negative errno on failure.

mpipe_player_wait_quit()

int mpipe_player_wait_quit

(

struct mpipe_player *

player

)

#include <mpipe_player.h>

Block until the player worker exits.

Returns once the pipeline has been stopped and the worker thread is about to exit, i.e. after a quit has been requested (typically via the "q" / "player quit" shell command or mpipe_player_quit). This lets an application's main thread wait for the user to finish while the shell drives the player.

Note

This only waits; call mpipe_player_deinit afterwards to join the worker and release the player's resources.

Parameters

player

Player initialized with mpipe_player_init.

Return values

0

Success.