Gtk.MediaStream¶

class — extends GObject.Object, Gdk.Paintable

The integration point for media playback inside GTK.

GTK provides an implementation of the GtkMediaStream interface that is called MediaFile.

Apart from application-facing API for stream playback, GtkMediaStream has a number of APIs that are only useful for implementations and should not be used in applications: MediaStream.prepared, MediaStream.unprepared, MediaStream.update, MediaStream.ended, MediaStream.seek_success, MediaStream.seek_failed, MediaStream.gerror, MediaStream.error, MediaStream.error_valist.

Methods¶

gerror¶

def gerror(self, error: GLib.Error) -> None

Sets self into an error state.

This will pause the stream (you can check for an error via MediaStream.get_error in your GtkMediaStream.pause() implementation), abort pending seeks and mark the stream as prepared.

if the stream is already in an error state, this call will be ignored and the existing error will be retained.

To unset an error, the stream must be reset via a call to MediaStream.unprepared.

Parameters:

error — the GError to set

get_duration¶

def get_duration(self) -> int

Gets the duration of the stream.

If the duration is not known, 0 will be returned.

get_ended¶

def get_ended(self) -> bool

Returns whether the streams playback is finished.

get_error¶

def get_error(self) -> GLib.Error | None

If the stream is in an error state, returns the GError explaining that state.

Any type of error can be reported here depending on the implementation of the media stream.

A media stream in an error cannot be operated on, calls like MediaStream.play or MediaStream.seek will not have any effect.

GtkMediaStream itself does not provide a way to unset an error, but implementations may provide options. For example, a MediaFile will unset errors when a new source is set, e.g. with MediaFile.set_file.

get_loop¶

def get_loop(self) -> bool

Returns whether the stream is set to loop.

See MediaStream.set_loop for details.

get_muted¶

def get_muted(self) -> bool

Returns whether the audio for the stream is muted.

See MediaStream.set_muted for details.

get_playing¶

def get_playing(self) -> bool

Return whether the stream is currently playing.

get_timestamp¶

def get_timestamp(self) -> int

Returns the current presentation timestamp in microseconds.

get_volume¶

def get_volume(self) -> float

Returns the volume of the audio for the stream.

See MediaStream.set_volume for details.

has_audio¶

def has_audio(self) -> bool

Returns whether the stream has audio.

has_video¶

def has_video(self) -> bool

Returns whether the stream has video.

is_prepared¶

def is_prepared(self) -> bool

Returns whether the stream has finished initializing.

At this point the existence of audio and video is known.

is_seekable¶

def is_seekable(self) -> bool

Checks if a stream may be seekable.

This is meant to be a hint. Streams may not allow seeking even if this function returns True. However, if this function returns False, streams are guaranteed to not be seekable and user interfaces may hide controls that allow seeking.

It is allowed to call MediaStream.seek on a non-seekable stream, though it will not do anything.

is_seeking¶

def is_seeking(self) -> bool

Checks if there is currently a seek operation going on.

pause¶

def pause(self) -> None

Pauses playback of the stream.

If the stream is not playing, do nothing.

play¶

def play(self) -> None

Starts playing the stream.

If the stream is in error or already playing, do nothing.

realize¶

def realize(self, surface: Gdk.Surface) -> None

Called by users to attach the media stream to a GdkSurface they manage.

The stream can then access the resources of surface for its rendering purposes. In particular, media streams might want to create a GdkGLContext or sync to the GdkFrameClock.

Whoever calls this function is responsible for calling MediaStream.unrealize before either the stream or surface get destroyed.

Multiple calls to this function may happen from different users of the video, even with the same surface. Each of these calls must be followed by its own call to MediaStream.unrealize.

It is not required to call this function to make a media stream work.

Parameters:

surface — a GdkSurface

seek¶

def seek(self, timestamp: int) -> None

Start a seek operation on self to timestamp.

If timestamp is out of range, it will be clamped.

Seek operations may not finish instantly. While a seek operation is in process, the MediaStream.seeking property will be set.

When calling MediaStream.seek during an ongoing seek operation, the new seek will override any pending seek.

Parameters:

timestamp — timestamp to seek to.

seek_failed¶

def seek_failed(self) -> None

Ends a seek operation started via GtkMediaStream.seek() as a failure.

This will not cause an error on the stream and will assume that playback continues as if no seek had happened.

See MediaStream.seek_success for the other way of ending a seek.

seek_success¶

def seek_success(self) -> None

Ends a seek operation started via GtkMediaStream.seek() successfully.

This function will unset the GtkMediaStream:ended property if it was set.

See MediaStream.seek_failed for the other way of ending a seek.

set_loop¶

def set_loop(self, loop: bool) -> None

Sets whether the stream should loop.

In this case, it will attempt to restart playback from the beginning instead of stopping at the end.

Not all streams may support looping, in particular non-seekable streams. Those streams will ignore the loop setting and just end.

Parameters:

loop — True if the stream should loop

set_muted¶

def set_muted(self, muted: bool) -> None

Sets whether the audio stream should be muted.

Muting a stream will cause no audio to be played, but it does not modify the volume. This means that muting and then unmuting the stream will restore the volume settings.

If the stream has no audio, calling this function will still work but it will not have an audible effect.

Parameters:

muted — True if the stream should be muted

set_playing¶

def set_playing(self, playing: bool) -> None

Starts or pauses playback of the stream.

Parameters:

playing — whether to start or pause playback

set_volume¶

def set_volume(self, volume: float) -> None

Sets the volume of the audio stream.

This function call will work even if the stream is muted.

The given volume should range from 0.0 for silence to 1.0 for as loud as possible. Values outside of this range will be clamped to the nearest value.

If the stream has no audio or is muted, calling this function will still work but it will not have an immediate audible effect. When the stream is unmuted, the new volume setting will take effect.

Parameters:

volume — New volume of the stream from 0.0 to 1.0

stream_ended¶

def stream_ended(self) -> None

Pauses the media stream and marks it as ended.

This is a hint only, calls to MediaStream.play may still happen.

The media stream must be prepared when this function is called.

stream_prepared¶

def stream_prepared(self, has_audio: bool, has_video: bool, seekable: bool, duration: int) -> None

Called by GtkMediaStream implementations to advertise the stream being ready to play and providing details about the stream.

Note that the arguments are hints. If the stream implementation cannot determine the correct values, it is better to err on the side of caution and return True. User interfaces will use those values to determine what controls to show.

This function may not be called again until the stream has been reset via MediaStream.stream_unprepared.

Parameters:

has_audio — True if the stream should advertise audio support
has_video — True if the stream should advertise video support
seekable — True if the stream should advertise seekability
duration — The duration of the stream or 0 if unknown

stream_unprepared¶

def stream_unprepared(self) -> None

Resets a given media stream implementation.

MediaStream.stream_prepared can then be called again.

This function will also reset any error state the stream was in.

unrealize¶

def unrealize(self, surface: Gdk.Surface) -> None

Undoes a previous call to MediaStream.realize.

This causes the stream to release all resources it had allocated from surface.

Parameters:

surface — the GdkSurface the stream was realized with

update¶

def update(self, timestamp: int) -> None

Media stream implementations should regularly call this function to update the timestamp reported by the stream.

It is up to implementations to call this at the frequency they deem appropriate.

The media stream must be prepared when this function is called.

Parameters:

timestamp — the new timestamp

Virtual methods¶

do_pause¶

def do_pause(self) -> None

Pauses playback of the stream.

If the stream is not playing, do nothing.

do_play¶

def do_play(self) -> bool

do_realize¶

def do_realize(self, surface: Gdk.Surface) -> None

Called by users to attach the media stream to a GdkSurface they manage.

The stream can then access the resources of surface for its rendering purposes. In particular, media streams might want to create a GdkGLContext or sync to the GdkFrameClock.

Whoever calls this function is responsible for calling MediaStream.unrealize before either the stream or surface get destroyed.

Multiple calls to this function may happen from different users of the video, even with the same surface. Each of these calls must be followed by its own call to MediaStream.unrealize.

It is not required to call this function to make a media stream work.

Parameters:

surface — a GdkSurface

do_seek¶

def do_seek(self, timestamp: int) -> None

Start a seek operation on self to timestamp.

If timestamp is out of range, it will be clamped.

Seek operations may not finish instantly. While a seek operation is in process, the MediaStream.seeking property will be set.

When calling MediaStream.seek during an ongoing seek operation, the new seek will override any pending seek.

Parameters:

timestamp — timestamp to seek to.

do_unrealize¶

def do_unrealize(self, surface: Gdk.Surface) -> None

Undoes a previous call to MediaStream.realize.

This causes the stream to release all resources it had allocated from surface.

Parameters:

surface — the GdkSurface the stream was realized with

do_update_audio¶

def do_update_audio(self, muted: bool, volume: float) -> None

Properties¶

duration¶

duration: int  # read-only

The stream's duration in microseconds or 0 if unknown.

ended¶

ended: bool  # read-only

Set when playback has finished.

error¶

error: GLib.Error  # read-only

None for a properly working stream or the GError that the stream is in.

has_audio¶

has_audio: bool  # read-only

Whether the stream contains audio.

has_video¶

has_video: bool  # read-only

Whether the stream contains video.

loop¶

loop: bool  # read/write

Try to restart the media from the beginning once it ended.

muted¶

muted: bool  # read/write

Whether the audio stream should be muted.

playing¶

playing: bool  # read/write

Whether the stream is currently playing.

prepared¶

prepared: bool  # read-only

Whether the stream has finished initializing and existence of audio and video is known.

seekable¶

seekable: bool  # read-only

Set unless the stream is known to not support seeking.

seeking¶

seeking: bool  # read-only

Set while a seek is in progress.

timestamp¶

timestamp: int  # read-only

The current presentation timestamp in microseconds.

volume¶

volume: float  # read/write

Volume of the audio stream.