Package org.gnome.gtk

Class MediaStream

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gtk.MediaStream

All Implemented Interfaces:

Proxy, Paintable

Direct Known Subclasses:

MediaFile, MediaStream.MediaStreamImpl

@Generated("io.github.jwharm.JavaGI")
public abstract class MediaStream
extends GObject
implements Paintable

GtkMediaStream is 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: prepared(boolean, boolean, boolean, long), unprepared(), update(long), ended(), seekSuccess(), seekFailed(), gerror(org.gnome.glib.GError), error(org.gnome.glib.Quark, int, java.lang.String, java.lang.Object...), MediaStream#errorValist.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MediaStream.Builder<B extends MediaStream.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static class	MediaStream.MediaStreamClass
static class	MediaStream.MediaStreamImpl	The MediaStreamImpl type represents a native instance of the abstract MediaStream class.

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Nested classes/interfaces inherited from interface org.gnome.gdk.Paintable

Paintable.InvalidateContentsCallback, Paintable.InvalidateSizeCallback, Paintable.PaintableImpl, Paintable.PaintableInterface

Constructor Summary

Constructors

Constructor	Description
MediaStream(MemorySegment address)	Create a MediaStream proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected MediaStream	asParent()	Returns this instance as if it were its parent type.
static MediaStream.Builder<? extends MediaStream.Builder>	builder()	A MediaStream.Builder object constructs a MediaStream with the specified properties.
void	ended()	Deprecated. Use streamEnded() instead
void	error(Quark domain, int code, String format, Object... varargs)	Sets this MediaStream into an error state using a printf()-style format string.
void	gerror(GError error)	Sets this MediaStream into an error state.
long	getDuration()	Gets the duration of the stream.
boolean	getEnded()	Returns whether the streams playback is finished.
GError	getError()	If the stream is in an error state, returns the GError explaining that state.
boolean	getLoop()	Returns whether the stream is set to loop.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
boolean	getMuted()	Returns whether the audio for the stream is muted.
boolean	getPlaying()	Return whether the stream is currently playing.
long	getTimestamp()	Returns the current presentation timestamp in microseconds.
static Type	getType()	Get the GType of the MediaStream class
double	getVolume()	Returns the volume of the audio for the stream.
boolean	hasAudio()	Returns whether the stream has audio.
boolean	hasVideo()	Returns whether the stream has video.
boolean	isPrepared()	Returns whether the stream has finished initializing.
boolean	isSeekable()	Checks if a stream may be seekable.
boolean	isSeeking()	Checks if there is currently a seek operation going on.
void	pause()	Pauses playback of the stream.
boolean	play()	Starts playing the stream.
void	prepared(boolean hasAudio, boolean hasVideo, boolean seekable, long duration)	Deprecated. Use streamPrepared(boolean, boolean, boolean, long) instead.
void	realize(Surface surface)	Called by users to attach the media stream to a GdkSurface they manage.
void	seek(long timestamp)	Start a seek operation on this MediaStream to timestamp.
void	seekFailed()	Ends a seek operation started via GtkMediaStream.seek() as a failure.
void	seekSuccess()	Ends a seek operation started via GtkMediaStream.seek() successfully.
void	setLoop(boolean loop)	Sets whether the stream should loop.
void	setMuted(boolean muted)	Sets whether the audio stream should be muted.
void	setPlaying(boolean playing)	Starts or pauses playback of the stream.
void	setVolume(double volume)	Sets the volume of the audio stream.
void	streamEnded()	Pauses the media stream and marks it as ended.
void	streamPrepared(boolean hasAudio, boolean hasVideo, boolean seekable, long duration)	Called by GtkMediaStream implementations to advertise the stream being ready to play and providing details about the stream.
void	streamUnprepared()	Resets a given media stream implementation.
void	unprepared()	Deprecated. Use streamUnprepared() instead.
void	unrealize(Surface surface)	Undoes a previous call to gtk_media_stream_realize().
void	update(long timestamp)	Media stream implementations should regularly call this function to update the timestamp reported by the stream.
protected void	updateAudio(boolean muted, double volume)

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, getPrivate, readGClass, writeGClass

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.gnome.gdk.Paintable

computeConcreteSize, emitInvalidateContents, emitInvalidateSize, getCurrentImage, getFlags, getIntrinsicAspectRatio, getIntrinsicHeight, getIntrinsicWidth, invalidateContents, invalidateSize, onInvalidateContents, onInvalidateSize, snapshot

Methods inherited from interface io.github.jwharm.javagi.base.Proxy

handle

Constructor Details

MediaStream

public MediaStream(MemorySegment address)

Create a MediaStream proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the MediaStream class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected MediaStream asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

ended

@Deprecated
public void ended()

Deprecated.

Use streamEnded() instead

Pauses the media stream and marks it as ended.

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

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

error

public void error(Quark domain,
 int code,
 String format,
 Object... varargs)

Sets this MediaStream into an error state using a printf()-style format string.

This is a utility function that calls gerror(org.gnome.glib.GError). See that function for details.

Parameters:

domain - error domain

code - error code

format - printf()-style format for error message

varargs - parameters for message format

gerror

public void gerror(GError error)

Sets this MediaStream into an error state.

This will pause the stream (you can check for an error via getError() 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 unprepared().

Parameters:

error - the GError to set

getDuration

public long getDuration()

Gets the duration of the stream.

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

Returns:

the duration of the stream or 0 if not known.

getEnded

public boolean getEnded()

Returns whether the streams playback is finished.

Returns:

true if playback is finished

getError

public GError getError()

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 play() or seek(long) 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.setFile(org.gnome.gio.File).

Returns:

null if not in an error state or the GError of the stream

getLoop

public boolean getLoop()

Returns whether the stream is set to loop.

See setLoop(boolean) for details.

Returns:

true if the stream should loop

getMuted

public boolean getMuted()

Returns whether the audio for the stream is muted.

See setMuted(boolean) for details.

Returns:

true if the stream is muted

getPlaying

public boolean getPlaying()

Return whether the stream is currently playing.

Returns:

true if the stream is playing

getTimestamp

public long getTimestamp()

Returns the current presentation timestamp in microseconds.

Returns:

the timestamp in microseconds

getVolume

public double getVolume()

Returns the volume of the audio for the stream.

See setVolume(double) for details.

Returns:

volume of the stream from 0.0 to 1.0

hasAudio

public boolean hasAudio()

Returns whether the stream has audio.

Returns:

true if the stream has audio

hasVideo

public boolean hasVideo()

Returns whether the stream has video.

Returns:

true if the stream has video

isPrepared

public boolean isPrepared()

Returns whether the stream has finished initializing.

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

Returns:

true if the stream is prepared

isSeekable

public boolean isSeekable()

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 seek(long) on a non-seekable stream, though it will not do anything.

Returns:

true if the stream may support seeking

isSeeking

public boolean isSeeking()

Checks if there is currently a seek operation going on.

Returns:

true if a seek operation is ongoing.

pause

public void pause()

Pauses playback of the stream.

If the stream is not playing, do nothing.

play

public boolean play()

Starts playing the stream.

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

prepared

@Deprecated
public void prepared(boolean hasAudio,
 boolean hasVideo,
 boolean seekable,
 long duration)

Deprecated.

Use streamPrepared(boolean, boolean, boolean, long) instead.

Same as gtk_media_stream_stream_prepared().

Parameters:

hasAudio - true if the stream should advertise audio support

hasVideo - 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

realize

public void realize(Surface surface)

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 unrealize(org.gnome.gdk.Surface) 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 unrealize(org.gnome.gdk.Surface).

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

Parameters:

surface - a GdkSurface

seek

public void seek(long timestamp)

Start a seek operation on this MediaStream 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.

Parameters:

timestamp - timestamp to seek to.

seekFailed

public void seekFailed()

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 seekSuccess() for the other way of ending a seek.

seekSuccess

public void seekSuccess()

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

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

See seekFailed() for the other way of ending a seek.

setLoop

public void setLoop(boolean loop)

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

setMuted

public void setMuted(boolean muted)

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

setPlaying

public void setPlaying(boolean playing)

Starts or pauses playback of the stream.

Parameters:

playing - whether to start or pause playback

setVolume

public void setVolume(double volume)

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

streamEnded

public void streamEnded()

Pauses the media stream and marks it as ended.

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

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

streamPrepared

public void streamPrepared(boolean hasAudio,
 boolean hasVideo,
 boolean seekable,
 long duration)

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 streamUnprepared().

Parameters:

hasAudio - true if the stream should advertise audio support

hasVideo - 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

streamUnprepared

public void streamUnprepared()

Resets a given media stream implementation.

streamPrepared(boolean, boolean, boolean, long) can then be called again.

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

unprepared

@Deprecated
public void unprepared()

Deprecated.

Use streamUnprepared() instead.

Same as gtk_media_stream_stream_unprepared().

unrealize

public void unrealize(Surface surface)

Undoes a previous call to gtk_media_stream_realize().

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

Parameters:

surface - the GdkSurface the stream was realized with

update

public void update(long 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.

Parameters:

timestamp - the new timestamp

updateAudio

protected void updateAudio(boolean muted,
 double volume)

builder

public static MediaStream.Builder<? extends MediaStream.Builder> builder()

A MediaStream.Builder object constructs a MediaStream with the specified properties. Use the various set...() methods to set properties, and finish construction with MediaStream.Builder.build().