Clapper.MediaItem¶

Subclasses:: None

Methods¶

Inherited:: Gst.Object (29), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (uri)
class	`new_cached` (uri, location)
class	`new_from_file` (file)
	`get_cache_location` ()
	`get_container_format` ()
	`get_duration` ()
	`get_id` ()
	`get_redirect_uri` ()
	`get_suburi` ()
	`get_tags` ()
	`get_timeline` ()
	`get_title` ()
	`get_uri` ()
	`populate_tags` (tags)
	`set_suburi` (suburi)

Virtual Methods¶

Inherited:: Gst.Object (1), GObject.Object (7)

Properties¶

Inherited:: Gst.Object (2)

Name	Type	Flags	Short Description
`cache-location`	`str`	r/w/co/en
`container-format`	`str`	d/r/en	`deprecated`
`duration`	`float`	r/en
`id`	`int`	r/en
`redirect-uri`	`str`	r/en
`suburi`	`str`	r/w/en
`tags`	`Gst.TagList`	r/en
`timeline`	`Clapper.Timeline`	r/en
`title`	`str`	r/en
`uri`	`str`	r/w/co/en

Signals¶

Inherited:: Gst.Object (1), GObject.Object (1)

Fields¶

Inherited:: Gst.Object (1), GObject.Object (1)

Class Details¶

class Clapper.MediaItem(**kwargs)¶

Bases:: Gst.Object
Abstract:: No
Structure:: Clapper.MediaItemClass

Represents a media item.

A newly created media item must be added to player [class`Clapper`.Queue] first in order to be played.

classmethod new(uri)¶

Parameters:: uri (str) – a media URI
Returns:: a new Clapper.MediaItem.
Return type:: Clapper.MediaItem

Creates new Clapper.MediaItem from URI.

Use one of the URI protocols supported by plugins in #GStreamer installation. For local files you can use either “file” protocol or [ctor`Clapper`.MediaItem.new_from_file] method.

It is considered a programmer error trying to create new media item from invalid URI. If URI is valid, but unsupported by installed plugins on user system, [class`Clapper`.Player] will emit a [signal`Clapper`.Player::missing-plugin] signal upon playback.

classmethod new_cached(uri, location)¶

Parameters:

uri (str) – a media URI
location (str or None) – a path to downloaded file

Returns:

a new Clapper.MediaItem.

Return type:

Clapper.MediaItem

Same as [ctor`Clapper`.MediaItem.new], but allows to provide a location of a cache file where particular media at uri is supposed to be found.

File at location existence will be checked upon starting playback of created item. If cache file is not found, media item uri will be used as fallback. In this case when [property`Clapper`.Player:download-enabled] is set to True, item will be downloaded and cached again if possible.

New in version 0.8.

classmethod new_from_file(file)¶

Parameters:: file (Gio.File) – a Gio.File
Returns:: a new Clapper.MediaItem.
Return type:: Clapper.MediaItem

Creates new Clapper.MediaItem from Gio.File.

Same as [ctor`Clapper`.MediaItem.new], but uses a [iface`Gio`.File] for convenience in some situations instead of an URI.

get_cache_location()¶

Returns:: a cache file location of Clapper.MediaItem.
Return type:: str or None

Get downloaded cache file location of Clapper.MediaItem.

New in version 0.10.

get_container_format()¶

Returns:: media container format.
Return type:: str or None

Get media item container format.

Deprecated since version 0.10: Get container-format from [property`Clapper`.MediaItem:tags] instead.

get_duration()¶

Returns:: media duration.
Return type:: float

Get media item duration as decimal number in seconds.

get_id()¶

Returns:: an ID of Clapper.MediaItem.
Return type:: int

Get the unique ID of Clapper.MediaItem.

get_redirect_uri()¶

Returns:: a redirected URI of Clapper.MediaItem.
Return type:: str or None

Get permanent redirect URI of Clapper.MediaItem.

New in version 0.10.

get_suburi()¶

Returns:: an additional URI of Clapper.MediaItem.
Return type:: str or None

Get the additional URI of Clapper.MediaItem.

get_tags()¶

Returns:: a Gst.TagList.
Return type:: Gst.TagList

Get readable list of tags stored in media item.

New in version 0.10.

get_timeline()¶

Returns:: a Clapper.Timeline of item.
Return type:: Clapper.Timeline

Get the [class`Clapper`.Timeline] associated with self.

get_title()¶

Returns:: media title.
Return type:: str or None

Get media item title.

The title can be either text detected by media discovery once it completes. Otherwise whenever possible this will try to return a title extracted from media URI e.g. basename without extension for local files.

get_uri()¶

Returns:: an URI of Clapper.MediaItem.
Return type:: str

Get the URI of Clapper.MediaItem.

populate_tags(tags)¶

Parameters:: tags (Gst.TagList) – a Gst.TagList of GLOBAL scope
Returns:: whether at least one tag got updated.
Return type:: bool

Populate non-existing tags in self tag list.

Passed tags must use [enum`Gst`.TagScope.GLOBAL] scope.

Note that tags are automatically determined during media playback and those take precedence. This function can be useful if an app can determine some tags that are not in media metadata or for filling item with some initial/cached tags to display in UI before playback.

When a tag already exists in the tag list (was populated) this function will not overwrite it. If you really need to permanently override some tags in media, you can use taginject element as player video/audio filter instead.

New in version 0.10.

set_suburi(suburi)¶

Parameters:: suburi (str) – an additional URI

Set the additional URI of Clapper.MediaItem.

This is typically used to add an external subtitles URI to the self.

Property Details¶

Clapper.MediaItem.props.cache_location¶

Name:: cache-location
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY, EXPLICIT_NOTIFY

Media downloaded cache file location.

This can be either set for newly created media items or it will be updated after download is completed if [property`Clapper`.Player:download-enabled] is set.

NOTE: This property was added in 0.8 as write at construct only. It can also be read only since Clapper 0.10.

New in version 0.8.

Clapper.MediaItem.props.container_format¶

Name:: container-format
Type:: str
Default Value:: None
Flags:: DEPRECATED, READABLE, EXPLICIT_NOTIFY

Media container format.

Deprecated since version 0.10: Get container-format from [property`Clapper`.MediaItem:tags] instead.

Clapper.MediaItem.props.duration¶

Name:: duration
Type:: float
Default Value:: 0.0
Flags:: READABLE, EXPLICIT_NOTIFY

Media duration as a decimal number in seconds.

This might be a different value compared to duration from [property`Clapper`.MediaItem:tags], as this value is updated during decoding instead of being a fixed value from metadata.

Clapper.MediaItem.props.id¶

Name:: id
Type:: int
Default Value:: 4294967295
Flags:: READABLE, EXPLICIT_NOTIFY

Media Item ID.

Clapper.MediaItem.props.redirect_uri¶

Name:: redirect-uri
Type:: str
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

Media permanent redirect URI.

Changes when player determines a new redirect for given media item. This will also happen when item URI leads to a playlist. Once playlist is parsed, item is merged with the first item on that playlist and the remaining items are appended to the playback queue after that item position.

Once redirect URI in item is present, player will use that URI instead of the default one. Cache location takes precedence over both URIs through.

New in version 0.10.

Clapper.MediaItem.props.suburi¶

Name:: suburi
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Media additional URI.

Clapper.MediaItem.props.tags¶

Name:: tags
Type:: Gst.TagList
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

A readable list of tags stored in media item.

New in version 0.10.

Clapper.MediaItem.props.timeline¶

Name:: timeline
Type:: Clapper.Timeline
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

Media timeline.

Clapper.MediaItem.props.title¶

Name:: title
Type:: str
Default Value:: None
Flags:: READABLE, EXPLICIT_NOTIFY

Media title.

This might be a different string compared to title from [property`Clapper`.MediaItem:tags], as this gives parsed title from file name/URI as fallback when no title tag.

Clapper.MediaItem.props.uri¶

Name:: uri
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY, EXPLICIT_NOTIFY

Media URI.