Mirage.Session¶

Subclasses:: None

Methods¶

Inherited:: Mirage.Object (2), GObject.Object (37), Mirage.Contextual (8)
Structs:: GObject.ObjectClass (5)

	`add_language` (code, language)
	`add_track_by_index` (index, track)
	`add_track_by_number` (number, track)
	`enumerate_languages` (func, *user_data)
	`enumerate_tracks` (func, *user_data)
	`get_cdtext_data` ()
	`get_language_by_code` (code)
	`get_language_by_index` (index)
	`get_leadout_length` ()
	`get_mcn` ()
	`get_next` ()
	`get_number_of_languages` ()
	`get_number_of_tracks` ()
	`get_prev` ()
	`get_session_type` ()
	`get_track_after` (track)
	`get_track_before` (track)
	`get_track_by_address` (address)
	`get_track_by_index` (index)
	`get_track_by_number` (number)
	`layout_contains_address` (address)
	`layout_get_first_track` ()
	`layout_get_length` ()
	`layout_get_session_number` ()
	`layout_get_start_sector` ()
	`layout_set_first_track` (first_track)
	`layout_set_session_number` (number)
	`layout_set_start_sector` (start_sector)
	`remove_language_by_code` (code)
	`remove_language_by_index` (index)
	`remove_language_by_object` (language)
	`remove_track_by_index` (index)
	`remove_track_by_number` (number)
	`remove_track_by_object` (track)
	`set_cdtext_data` (data)
	`set_leadout_length` (length)
	`set_mcn` (mcn)
	`set_session_type` (type)

Virtual Methods¶

Inherited:: GObject.Object (7), Mirage.Contextual (2)

Properties¶

None

Signals¶

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

Name	Short Description
`layout-changed`	Emitted when a layout of `Mirage.Session` changed in a way that causes a bottom-up change.

Fields¶

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

Name	Type	Access	Description
parent_instance	`Mirage.Object`	r

Class Details¶

class Mirage.Session(**kwargs)¶

Bases:: Mirage.Object
Abstract:: No
Structure:: Mirage.SessionClass

All the fields in the Mirage.Session structure are private to the Mirage.Session implementation and should never be accessed directly.

add_language(code, language)¶

Parameters:

code (int) – language code for the added language
language (Mirage.Language) – a Mirage.Language to be added

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Adds language to session.

code is language code that should be assigned to added language. If language with that code is already present in the session, the function fails.

add_track_by_index(index, track)¶

Parameters:

index (int) – index at which track should be added
track (Mirage.Track) – a Mirage.Track to be added

Adds track to session layout.

index is the index at which track is added. Negative index denotes index going backwards (i.e. -1 adds track at the end, -2 adds track second-to-last, etc.). If index, either negative or positive, is too big, track is respectively added at the beginning or at the end of the layout.

Causes bottom-up change.

add_track_by_number(number, track)¶

Parameters:

number (int) – track number for the added track
track (Mirage.Track) – a Mirage.Track to be added

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Adds track to session layout.

number is track number that should be assigned to added track. It determines track’s position in the layout. If track with that number already exists in the layout, the function fails.

Causes bottom-up change.

enumerate_languages(func, *user_data)¶

Parameters:

func (Mirage.EnumLanguageCallback) – callback function
user_data (object or None) – data to be passed to callback function

Returns:

True on success, False on failure

Return type:

bool

Iterates over languages list, calling func for each language.

If func returns False, the function immediately returns False.

enumerate_tracks(func, *user_data)¶

Parameters:

func (Mirage.EnumTrackCallback) – callback function
user_data (object or None) – data to be passed to callback function

Returns:

True on success, False on failure

Return type:

bool

Iterates over tracks list, calling func for each track in the layout.

If func returns False, the function immediately returns False.

get_cdtext_data()¶

Raises:

GLib.Error

Returns:

True on success, False on failure

data:: location to return buffer with encoded CD-TEXT data

Return type:

(bool, data: bytes)

Returns CD-TEXT data for session. It internally creates and uses Mirage.CdTextCoder object as an encoder to encode data from Mirage.Language objects from both session and its tracks. Buffer with encoded data is stored in data; it should be freed with GLib.free() when no longer needed.

get_language_by_code(code)¶

Parameters:: code (int) – language code of language to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Language on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Language

Retrieves language by language code.

get_language_by_index(index)¶

Parameters:: index (int) – index of language to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Language on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Language

Retrieves language by index. If index is negative, languages from the end of session are retrieved (e.g. -1 is for last language, -2 for second-to-last language, etc.). If index is out of range, regardless of the sign, the function fails.

get_leadout_length()¶

Returns:: leadout length
Return type:: int

Retrieves session’s leadout length. The returned length is given in sectors.

Intended for internal use only.

get_mcn()¶

Returns:: pointer to MCN string, or None. The string belongs to the object and should not be modified.
Return type:: str

Retrieves MCN.

get_next()¶

Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

Retrieves session that is placed after self in disc layout.

get_number_of_languages()¶

Returns:: number of languages
Return type:: int

Retrieves number of languages the session contains.

get_number_of_tracks()¶

Returns:: number of tracks
Return type:: int

Retrieves number of tracks in the session layout.

get_prev()¶

Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

Retrieves session that is placed before self in disc layout.

get_session_type()¶

Returns:: session type
Return type:: Mirage.SessionType

Retrieves session type.

get_track_after(track)¶

Parameters:: track (Mirage.Track) – a track
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

Retrieves track that comes after track.

get_track_before(track)¶

Parameters:: track (Mirage.Track) – a track
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

Retrieves track that comes before track.

get_track_by_address(address)¶

Parameters:: address (int) – address belonging to track to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

Retrieves track by address. address must be valid (disc-relative) sector address that is part of the track to be retrieved (i.e. lying between tracks’s start and end sector).

get_track_by_index(index)¶

Parameters:: index (int) – index of track to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

Retrieves track by index. If index is negative, tracks from the end of layout are retrieved (e.g. -1 is for last track, -2 for second-to-last track, etc.). If index is out of range, regardless of the sign, the function fails.

get_track_by_number(number)¶

Parameters:: number (int) – number of track to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

Retrieves track by track number.

layout_contains_address(address)¶

Parameters:: address (int) – address to be checked
Returns:: True if address falls inside session, False if it does not
Return type:: bool

Checks whether the session contains the given address or not.

layout_get_first_track()¶

Returns:: first track number
Return type:: int

Retrieves track number of the first track in the session layout.

Intended for internal use only.

layout_get_length()¶

Returns:: session layout length
Return type:: int

Retrieves length of the session layout. This means the length of all tracks combined, including lead-in and lead-out tracks. The returned length is given in sectors.

layout_get_session_number()¶

Returns:: session number
Return type:: int

Retrieves sessions’s session number.

layout_get_start_sector()¶

Returns:: start sector
Return type:: int

Retrieves start sector of the session layout.

Intended for internal use only.

layout_set_first_track(first_track)¶

Parameters:: first_track (int) – first track number

Sets first track number to first_track. This is a number that is assigned to the first track in the session layout.

Intended for internal use only.

Causes top-down change.

layout_set_session_number(number)¶

Parameters:: number (int) – session number

Sets sessions’s session number.

Intended for internal use only.

layout_set_start_sector(start_sector)¶

Parameters:: start_sector (int) – start sector

Sets start sector of the session layout to start_sector. This is a sector at which the first track in the session layout will start.

Intended for internal use only.

Causes top-down change.

remove_language_by_code(code)¶

Parameters:: code (int) – language code of language to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Removes language from session.

code is language code the language to be removed.

remove_language_by_index(index)¶

Parameters:: index (int) – index of language to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Removes language from session.

index is the index of the language to be removed. This function calls Mirage.Session.get_language_by_index() so index behavior is determined by that function.

remove_language_by_object(language)¶

Parameters:: language (Mirage.Language) – language object to be removed

Removes language from session.

language is a Mirage.Language object to be removed.

remove_track_by_index(index)¶

Parameters:: index (int) – index of track to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Removes track from session layout.

index is the index of the track to be removed. This function calls Mirage.Session.get_track_by_index() so index behavior is determined by that function.

Causes bottom-up change.

remove_track_by_number(number)¶

Parameters:: number (int) – track number of track to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Removes track from session layout.

number is track number of the track to be removed.

Causes bottom-up change.

remove_track_by_object(track)¶

Parameters:: track (Mirage.Track) – track object to be removed

Removes track from session layout.

track is a Mirage.Track object to be removed.

Causes bottom-up change.

set_cdtext_data(data)¶

Parameters:: data (bytes) – buffer containing encoded CD-TEXT data
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Sets CD-TEXT data for session. It internally creates and uses Mirage.CdTextCoder object as a decoder to decode data in data. Decoded data is stored in Mirage.Language objects in both session and its tracks. Therefore session must have same number of tracks as the encoded CD-TEXT data.

set_leadout_length(length)¶

Parameters:: length (int) – leadout length

Sets session’s leadout length to length. It does so by creating None fragment and adding it to leadout. This function is internally used to properly handle multi-session disc layouts. The length is given in sectors.

Intended for internal use only.

set_mcn(mcn)¶

Parameters:: mcn (str) – MCN

Sets MCN (Media Catalogue Number).

Because MCN is stored in subchannel data, this function silently fails if any of session’s tracks contains fragments with subchannel data provided.

Intended for internal use only.

set_session_type(type)¶

Parameters:: type (Mirage.SessionType) – session type

Sets session type. type must be one of Mirage.SessionType.

Signal Details¶

Mirage.Session.signals.layout_changed(session)¶

Signal Name:: layout-changed
Flags:: RUN_LAST
Parameters:: session (Mirage.Session) – The object which received the signal

Emitted when a layout of Mirage.Session changed in a way that causes a bottom-up change.