class Gtk::MediaStream

Overview

Gtk::MediaStream is the integration point for media playback inside GTK.

GTK provides an implementation of the Gtk::MediaStream interface that is called Gtk::MediaFile.

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

Included Modules

Direct Known Subclasses

Defined in:

lib/gi-crystal/src/auto/gtk-4.0/media_stream.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Gdk::Paintable

compute_concrete_size(specified_width : Float64, specified_height : Float64, default_width : Float64, default_height : Float64, concrete_width : Float64, concrete_height : Float64) : Nil compute_concrete_size, current_image : Gdk::Paintable current_image, flags : Gdk::PaintableFlags flags, intrinsic_aspect_ratio : Float64 intrinsic_aspect_ratio, intrinsic_height : Int32 intrinsic_height, intrinsic_width : Int32 intrinsic_width, invalidate_contents : Nil invalidate_contents, invalidate_contents_signal invalidate_contents_signal, invalidate_size : Nil invalidate_size, invalidate_size_signal invalidate_size_signal, snapshot(snapshot : Gdk::Snapshot, width : Float64, height : Float64) : Nil snapshot, to_unsafe to_unsafe

Class methods inherited from module Gdk::Paintable

g_type : UInt64 g_type, new_empty(intrinsic_width : Int32, intrinsic_height : Int32) : Gdk::Paintable new_empty

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new #

Initialize a new MediaStream.


def self.new(*, duration : Int64? = nil, ended : Bool? = nil, error : GLib::Error? = nil, has_audio : Bool? = nil, has_video : Bool? = nil, loop : Bool? = nil, muted : Bool? = nil, playing : Bool? = nil, prepared : Bool? = nil, seekable : Bool? = nil, seeking : Bool? = nil, timestamp : Int64? = nil, volume : Float64? = nil) #

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def duration : Int64 #

Gets the duration of the stream.

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


def ended : Bool #

Returns whether the streams playback is finished.


def ended? : Bool #

def error : GLib::Error? #

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 Gtk::MediaStream#play or Gtk::MediaStream#seek will not have any effect.

Gtk::MediaStream itself does not provide a way to unset an error, but implementations may provide options. For example, a Gtk::MediaFile will unset errors when a new source is set, e.g. with Gtk::MediaFile#file=.


def gerror(error : GLib::Error) : Nil #

Sets @self into an error state.

This will pause the stream (you can check for an error via Gtk::MediaStream#error in your Gtk::MediaStream.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 Gtk::MediaStream#unprepared.


def has_audio : Bool #

Returns whether the stream has audio.


def has_audio? : Bool #

def has_video : Bool #

Returns whether the stream has video.


def has_video? : Bool #

def is_prepared : Bool #

Returns whether the stream has finished initializing.

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


def is_seekable : 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 Gtk::MediaStream#seek on a non-seekable stream, though it will not do anything.


def is_seeking : Bool #

Checks if there is currently a seek operation going on.


def loop : Bool #

Returns whether the stream is set to loop.

See Gtk::MediaStream#loop= for details.


def loop=(loop : Bool) : Nil #

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.


def loop? : Bool #

def muted : Bool #

Returns whether the audio for the stream is muted.

See Gtk::MediaStream#muted= for details.


def muted=(muted : Bool) : Nil #

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.


def muted? : Bool #

def pause : Nil #

Pauses playback of the stream.

If the stream is not playing, do nothing.


def play : Nil #

Starts playing the stream.

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


def playing : Bool #

Return whether the stream is currently playing.


def playing=(playing : Bool) : Nil #

Starts or pauses playback of the stream.


def playing? : Bool #

def prepared=(value : Bool) : Bool #

def prepared? : Bool #

def realize(surface : Gdk::Surface) : Nil #

Called by users to attach the media stream to a Gdk::Surface they manage.

The stream can then access the resources of @surface for its rendering purposes. In particular, media streams might want to create a Gdk::GLContext or sync to the Gdk::FrameClock.

Whoever calls this function is responsible for calling 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 Gtk::MediaStream#unrealize.

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


def seek(timestamp : Int64) : Nil #

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 Gtk::MediaStream#seeking property will be set.

When calling gtk_media_stream_seek() during an ongoing seek operation, the new seek will override any pending seek.


def seek_failed : Nil #

Ends a seek operation started via Gtk::MediaStream.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 Gtk::MediaStream#seek_success for the other way of ending a seek.


def seek_success : Nil #

Ends a seek operation started via Gtk::MediaStream.seek() successfully.

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

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


def seekable? : Bool #

def seeking? : Bool #

def stream_ended : Nil #

Pauses the media stream and marks it as ended.

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

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


def stream_prepared(has_audio : Bool, has_video : Bool, seekable : Bool, duration : Int64) : Nil #

Called by Gtk::MediaStream 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 Gtk::MediaStream#stream_unprepared.


def stream_unprepared : Nil #

Resets a given media stream implementation.

Gtk::MediaStream#stream_prepared can then be called again.

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


def timestamp : Int64 #

Returns the current presentation timestamp in microseconds.


def unrealize(surface : Gdk::Surface) : Nil #

Undoes a previous call to gtk_media_stream_realize().

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


def update(timestamp : Int64) : Nil #

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.


def volume : Float64 #

Returns the volume of the audio for the stream.

See Gtk::MediaStream#volume= for details.


def volume=(volume : Float64) : Nil #

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.