gi-gtk-4.0.8: Gtk bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.Gtk.Objects.MediaStream

Description

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: MediaStream.prepared(), MediaStream.unprepared(), mediaStreamUpdate, MediaStream.ended(), mediaStreamSeekSuccess, mediaStreamSeekFailed, mediaStreamGerror, MediaStream.error(), MediaStream.error_valist().

Synopsis

Exported types

newtype MediaStream Source #

Memory-managed wrapper type.

Constructors

MediaStream (ManagedPtr MediaStream) 

Instances

Instances details
Eq MediaStream Source # 
Instance details

Defined in GI.Gtk.Objects.MediaStream

GObject MediaStream Source # 
Instance details

Defined in GI.Gtk.Objects.MediaStream

ManagedPtrNewtype MediaStream Source # 
Instance details

Defined in GI.Gtk.Objects.MediaStream

Methods

toManagedPtr :: MediaStream -> ManagedPtr MediaStream

TypedObject MediaStream Source # 
Instance details

Defined in GI.Gtk.Objects.MediaStream

Methods

glibType :: IO GType

HasParentTypes MediaStream Source # 
Instance details

Defined in GI.Gtk.Objects.MediaStream

IsGValue (Maybe MediaStream) Source #

Convert MediaStream to and from GValue. See toGValue and fromGValue.

Instance details

Defined in GI.Gtk.Objects.MediaStream

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe MediaStream -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe MediaStream)

type ParentTypes MediaStream Source # 
Instance details

Defined in GI.Gtk.Objects.MediaStream

type ParentTypes MediaStream = '[Object, Paintable]

class (GObject o, IsDescendantOf MediaStream o) => IsMediaStream o Source #

Type class for types which can be safely cast to MediaStream, for instance with toMediaStream.

Instances

Instances details
(GObject o, IsDescendantOf MediaStream o) => IsMediaStream o Source # 
Instance details

Defined in GI.Gtk.Objects.MediaStream

toMediaStream :: (MonadIO m, IsMediaStream o) => o -> m MediaStream Source #

Cast to MediaStream, for types for which this is known to be safe. For general casts, use castTo.

Methods

gerror

mediaStreamGerror Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> GError

error: the GError to set

-> m () 

Sets self into an error state.

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

getDuration

mediaStreamGetDuration Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Int64

Returns: the duration of the stream or 0 if not known.

Gets the duration of the stream.

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

getEnded

mediaStreamGetEnded Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if playback is finished

Returns whether the streams playback is finished.

getError

mediaStreamGetError Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m (Maybe GError)

Returns: Nothing if not in an error state or the GError of the stream

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 mediaStreamPlay or mediaStreamSeek 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 mediaFileSetFile.

getLoop

mediaStreamGetLoop Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if the stream should loop

Returns whether the stream is set to loop.

See mediaStreamSetLoop for details.

getMuted

mediaStreamGetMuted Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if the stream is muted

Returns whether the audio for the stream is muted.

See mediaStreamSetMuted for details.

getPlaying

mediaStreamGetPlaying Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if the stream is playing

Return whether the stream is currently playing.

getTimestamp

mediaStreamGetTimestamp Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Int64

Returns: the timestamp in microseconds

Returns the current presentation timestamp in microseconds.

getVolume

mediaStreamGetVolume Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Double

Returns: volume of the stream from 0.0 to 1.0

Returns the volume of the audio for the stream.

See mediaStreamSetVolume for details.

hasAudio

mediaStreamHasAudio Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if the stream has audio

Returns whether the stream has audio.

hasVideo

mediaStreamHasVideo Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if the stream has video

Returns whether the stream has video.

isPrepared

mediaStreamIsPrepared Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if the stream is prepared

Returns whether the stream has finished initializing.

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

isSeekable

mediaStreamIsSeekable Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if the stream may support seeking

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

isSeeking

mediaStreamIsSeeking Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m Bool

Returns: True if a seek operation is ongoing.

Checks if there is currently a seek operation going on.

pause

mediaStreamPause Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m () 

Pauses playback of the stream.

If the stream is not playing, do nothing.

play

mediaStreamPlay Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m () 

Starts playing the stream.

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

realize

mediaStreamRealize Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a, IsSurface b) 
=> a

self: a GtkMediaStream

-> b

surface: a GdkSurface

-> m () 

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 mediaStreamUnrealize 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 mediaStreamUnrealize.

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

seek

mediaStreamSeek Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> Int64

timestamp: timestamp to seek to.

-> m () 

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 mediaStreamSeek during an ongoing seek operation, the new seek will override any pending seek.

seekFailed

mediaStreamSeekFailed Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m () 

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

seekSuccess

mediaStreamSeekSuccess Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m () 

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

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

See mediaStreamSeekFailed for the other way of ending a seek.

setLoop

mediaStreamSetLoop Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> Bool

loop: True if the stream should loop

-> m () 

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.

setMuted

mediaStreamSetMuted Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> Bool

muted: True if the stream should be muted

-> m () 

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.

setPlaying

mediaStreamSetPlaying Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> Bool

playing: whether to start or pause playback

-> m () 

Starts or pauses playback of the stream.

setVolume

mediaStreamSetVolume Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> Double

volume: New volume of the stream from 0.0 to 1.0

-> m () 

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.

streamEnded

mediaStreamStreamEnded Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m () 

Pauses the media stream and marks it as ended.

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

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

Since: 4.4

streamPrepared

mediaStreamStreamPrepared Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> Bool

hasAudio: True if the stream should advertise audio support

-> Bool

hasVideo: True if the stream should advertise video support

-> Bool

seekable: True if the stream should advertise seekability

-> Int64

duration: The duration of the stream or 0 if unknown

-> m () 

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 mediaStreamStreamUnprepared.

Since: 4.4

streamUnprepared

mediaStreamStreamUnprepared Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> m () 

Resets a given media stream implementation.

mediaStreamStreamPrepared can then be called again.

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

Since: 4.4

unrealize

mediaStreamUnrealize Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a, IsSurface b) 
=> a

self: a GtkMediaStream previously realized

-> b

surface: the GdkSurface the stream was realized with

-> m () 

Undoes a previous call to mediaStreamRealize.

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

update

mediaStreamUpdate Source #

Arguments

:: (HasCallStack, MonadIO m, IsMediaStream a) 
=> a

self: a GtkMediaStream

-> Int64

timestamp: the new timestamp

-> m () 

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.

Properties

duration

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

getMediaStreamDuration :: (MonadIO m, IsMediaStream o) => o -> m Int64 Source #

Get the value of the “duration” property. When overloading is enabled, this is equivalent to

get mediaStream #duration

ended

Set when playback has finished.

getMediaStreamEnded :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “ended” property. When overloading is enabled, this is equivalent to

get mediaStream #ended

error

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

getMediaStreamError :: (MonadIO m, IsMediaStream o) => o -> m (Maybe GError) Source #

Get the value of the “error” property. When overloading is enabled, this is equivalent to

get mediaStream #error

hasAudio

Whether the stream contains audio.

getMediaStreamHasAudio :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “has-audio” property. When overloading is enabled, this is equivalent to

get mediaStream #hasAudio

hasVideo

Whether the stream contains video.

getMediaStreamHasVideo :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “has-video” property. When overloading is enabled, this is equivalent to

get mediaStream #hasVideo

loop

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

constructMediaStreamLoop :: (IsMediaStream o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “loop” property. This is rarely needed directly, but it is used by new.

getMediaStreamLoop :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “loop” property. When overloading is enabled, this is equivalent to

get mediaStream #loop

setMediaStreamLoop :: (MonadIO m, IsMediaStream o) => o -> Bool -> m () Source #

Set the value of the “loop” property. When overloading is enabled, this is equivalent to

set mediaStream [ #loop := value ]

muted

Whether the audio stream should be muted.

constructMediaStreamMuted :: (IsMediaStream o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “muted” property. This is rarely needed directly, but it is used by new.

getMediaStreamMuted :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “muted” property. When overloading is enabled, this is equivalent to

get mediaStream #muted

setMediaStreamMuted :: (MonadIO m, IsMediaStream o) => o -> Bool -> m () Source #

Set the value of the “muted” property. When overloading is enabled, this is equivalent to

set mediaStream [ #muted := value ]

playing

Whether the stream is currently playing.

constructMediaStreamPlaying :: (IsMediaStream o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “playing” property. This is rarely needed directly, but it is used by new.

getMediaStreamPlaying :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “playing” property. When overloading is enabled, this is equivalent to

get mediaStream #playing

setMediaStreamPlaying :: (MonadIO m, IsMediaStream o) => o -> Bool -> m () Source #

Set the value of the “playing” property. When overloading is enabled, this is equivalent to

set mediaStream [ #playing := value ]

prepared

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

constructMediaStreamPrepared :: (IsMediaStream o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “prepared” property. This is rarely needed directly, but it is used by new.

getMediaStreamPrepared :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “prepared” property. When overloading is enabled, this is equivalent to

get mediaStream #prepared

setMediaStreamPrepared :: (MonadIO m, IsMediaStream o) => o -> Bool -> m () Source #

Set the value of the “prepared” property. When overloading is enabled, this is equivalent to

set mediaStream [ #prepared := value ]

seekable

Set unless the stream is known to not support seeking.

getMediaStreamSeekable :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “seekable” property. When overloading is enabled, this is equivalent to

get mediaStream #seekable

seeking

Set while a seek is in progress.

getMediaStreamSeeking :: (MonadIO m, IsMediaStream o) => o -> m Bool Source #

Get the value of the “seeking” property. When overloading is enabled, this is equivalent to

get mediaStream #seeking

timestamp

The current presentation timestamp in microseconds.

getMediaStreamTimestamp :: (MonadIO m, IsMediaStream o) => o -> m Int64 Source #

Get the value of the “timestamp” property. When overloading is enabled, this is equivalent to

get mediaStream #timestamp

volume

Volume of the audio stream.

constructMediaStreamVolume :: (IsMediaStream o, MonadIO m) => Double -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “volume” property. This is rarely needed directly, but it is used by new.

getMediaStreamVolume :: (MonadIO m, IsMediaStream o) => o -> m Double Source #

Get the value of the “volume” property. When overloading is enabled, this is equivalent to

get mediaStream #volume

setMediaStreamVolume :: (MonadIO m, IsMediaStream o) => o -> Double -> m () Source #

Set the value of the “volume” property. When overloading is enabled, this is equivalent to

set mediaStream [ #volume := value ]