Gtk.MediaStream¶
- Subclasses:
Methods¶
- Inherited:
- Structs:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Virtual Methods¶
- Inherited:
|
|
|
|
|
|
|
|
|
|
|
Properties¶
Name |
Type |
Flags |
Short Description |
---|---|---|---|
r/en |
|||
r/en |
|||
r/en |
|||
r/en |
|||
r/en |
|||
r/w/en |
|||
r/w/en |
|||
r/w/en |
|||
r/w/en |
|||
r/en |
|||
r/en |
|||
r/en |
|||
r/w/en |
Signals¶
- Inherited:
Fields¶
- Inherited:
Name |
Type |
Access |
Description |
---|---|---|---|
parent_instance |
r |
Class Details¶
- class Gtk.MediaStream(**kwargs)¶
- Bases:
- Abstract:
Yes
- Structure:
GtkMediaStream
is the integration point for media playback inside GTK.GTK provides an implementation of the
GtkMediaStream
interface that is called [class`Gtk`.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: [method`Gtk`.MediaStream.prepared], [method`Gtk`.MediaStream.unprepared], [method`Gtk`.MediaStream.update], [method`Gtk`.MediaStream.ended], [method`Gtk`.MediaStream.seek_success], [method`Gtk`.MediaStream.seek_failed], [method`Gtk`.MediaStream.gerror], [method`Gtk`.MediaStream.error], [method`Gtk`.MediaStream.error_valist].- gerror(error)[source]¶
- Parameters:
error (
GLib.Error
) – theGError
to set
Sets self into an error state.
This will pause the stream (you can check for an error via [method`Gtk`.MediaStream.get_error] in your
Gtk.MediaStream.do_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 [method`Gtk`.MediaStream.unprepared].
- get_duration()[source]¶
- Returns:
the duration of the stream or 0 if not known.
- Return type:
Gets the duration of the stream.
If the duration is not known, 0 will be returned.
- get_error()[source]¶
- Returns:
None
if not in an error state or theGError
of the stream- Return type:
GLib.Error
orNone
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 [method`Gtk`.MediaStream.play] or [method`Gtk`.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 [class`Gtk`.MediaFile] will unset errors when a new source is set, e.g. with [method`Gtk`.MediaFile.set_file].
- get_loop()[source]¶
-
Returns whether the stream is set to loop.
See [method`Gtk`.MediaStream.set_loop] for details.
- get_muted()[source]¶
-
Returns whether the audio for the stream is muted.
See [method`Gtk`.MediaStream.set_muted] for details.
- get_timestamp()[source]¶
- Returns:
the timestamp in microseconds
- Return type:
Returns the current presentation timestamp in microseconds.
- get_volume()[source]¶
- Returns:
volume of the stream from 0.0 to 1.0
- Return type:
Returns the volume of the audio for the stream.
See [method`Gtk`.MediaStream.set_volume] for details.
- is_prepared()[source]¶
-
Returns whether the stream has finished initializing.
At this point the existence of audio and video is known.
- is_seekable()[source]¶
-
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 returnsFalse
, streams are guaranteed to not be seekable and user interfaces may hide controls that allow seeking.It is allowed to call [method`Gtk`.MediaStream.seek] on a non-seekable stream, though it will not do anything.
- play()[source]¶
Starts playing the stream.
If the stream is in error or already playing, do nothing.
- realize(surface)[source]¶
- Parameters:
surface (
Gdk.Surface
) – aGdkSurface
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 theGdkFrameClock
.Whoever calls this function is responsible for calling [method`Gtk`.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 [method`Gtk`.MediaStream.unrealize].
It is not required to call this function to make a media stream work.
- seek(timestamp)[source]¶
- Parameters:
timestamp (
int
) – timestamp to seek to.
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 [property`Gtk`.MediaStream:seeking] property will be set.
When calling
Gtk.MediaStream.seek
() during an ongoing seek operation, the new seek will override any pending seek.
- seek_failed()[source]¶
Ends a seek operation started via
Gtk.MediaStream.do_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 [method`Gtk`.MediaStream.seek_success] for the other way of ending a seek.
- seek_success()[source]¶
Ends a seek operation started via
Gtk.MediaStream.do_seek
() successfully.This function will unset the
Gtk.MediaStream
:ended
property if it was set.See [method`Gtk`.MediaStream.seek_failed] for the other way of ending a seek.
- set_loop(loop)[source]¶
-
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.
- set_muted(muted)[source]¶
-
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.
- set_playing(playing)[source]¶
- Parameters:
playing (
bool
) – whether to start or pause playback
Starts or pauses playback of the stream.
- set_volume(volume)[source]¶
- Parameters:
volume (
float
) – New volume of the stream from 0.0 to 1.0
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.
- stream_ended()[source]¶
Pauses the media stream and marks it as ended.
This is a hint only, calls to [method`Gtk`.MediaStream.play] may still happen.
The media stream must be prepared when this function is called.
New in version 4.4.
- stream_prepared(has_audio, has_video, seekable, duration)[source]¶
- Parameters:
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 [method`Gtk`.MediaStream.stream_unprepared].
New in version 4.4.
- stream_unprepared()[source]¶
Resets a given media stream implementation.
[method`Gtk`.MediaStream.stream_prepared] can then be called again.
This function will also reset any error state the stream was in.
New in version 4.4.
- unrealize(surface)[source]¶
- Parameters:
surface (
Gdk.Surface
) – theGdkSurface
the stream was realized with
Undoes a previous call to
Gtk.MediaStream.realize
().This causes the stream to release all resources it had allocated from surface.
- update(timestamp)[source]¶
- Parameters:
timestamp (
int
) – the new timestamp
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.
- do_pause() virtual¶
Pauses playback of the stream.
If the stream is not playing, do nothing.
- do_realize(surface) virtual¶
- Parameters:
surface (
Gdk.Surface
) – aGdkSurface
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 theGdkFrameClock
.Whoever calls this function is responsible for calling [method`Gtk`.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 [method`Gtk`.MediaStream.unrealize].
It is not required to call this function to make a media stream work.
- do_seek(timestamp) virtual¶
- Parameters:
timestamp (
int
) – timestamp to seek to.
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 [property`Gtk`.MediaStream:seeking] property will be set.
When calling
Gtk.MediaStream.seek
() during an ongoing seek operation, the new seek will override any pending seek.
- do_unrealize(surface) virtual¶
- Parameters:
surface (
Gdk.Surface
) – theGdkSurface
the stream was realized with
Undoes a previous call to
Gtk.MediaStream.realize
().This causes the stream to release all resources it had allocated from surface.
Property Details¶
- Gtk.MediaStream.props.duration¶
- Name:
duration
- Type:
- Default Value:
0
- Flags:
The stream’s duration in microseconds or 0 if unknown.
- Gtk.MediaStream.props.ended¶
- Name:
ended
- Type:
- Default Value:
- Flags:
Set when playback has finished.
- Gtk.MediaStream.props.error¶
- Name:
error
- Type:
- Default Value:
- Flags:
None
for a properly working stream or theGError
that the stream is in.
- Gtk.MediaStream.props.has_audio¶
- Name:
has-audio
- Type:
- Default Value:
- Flags:
Whether the stream contains audio.
- Gtk.MediaStream.props.has_video¶
- Name:
has-video
- Type:
- Default Value:
- Flags:
Whether the stream contains video.
- Gtk.MediaStream.props.loop¶
- Name:
loop
- Type:
- Default Value:
- Flags:
Try to restart the media from the beginning once it ended.
- Gtk.MediaStream.props.muted¶
- Name:
muted
- Type:
- Default Value:
- Flags:
Whether the audio stream should be muted.
- Gtk.MediaStream.props.playing¶
- Name:
playing
- Type:
- Default Value:
- Flags:
Whether the stream is currently playing.
- Gtk.MediaStream.props.prepared¶
- Name:
prepared
- Type:
- Default Value:
- Flags:
Whether the stream has finished initializing and existence of audio and video is known.
- Gtk.MediaStream.props.seekable¶
- Name:
seekable
- Type:
- Default Value:
- Flags:
Set unless the stream is known to not support seeking.
- Gtk.MediaStream.props.seeking¶
- Name:
seeking
- Type:
- Default Value:
- Flags:
Set while a seek is in progress.
- Gtk.MediaStream.props.timestamp¶
- Name:
timestamp
- Type:
- Default Value:
0
- Flags:
The current presentation timestamp in microseconds.
- Gtk.MediaStream.props.volume¶
- Name:
volume
- Type:
- Default Value:
1.0
- Flags:
Volume of the audio stream.