Mirage.Track¶

Subclasses:: None

Methods¶

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

	`add_fragment` (index, fragment)
	`add_index` (address)
	`add_language` (code, language)
	`enumerate_fragments` (func, *user_data)
	`enumerate_indices` (func, *user_data)
	`enumerate_languages` (func, *user_data)
	`find_fragment_with_subchannel` ()
	`get_adr` ()
	`get_ctl` ()
	`get_flags` ()
	`get_fragment_by_address` (address)
	`get_fragment_by_index` (index)
	`get_index_by_address` (address)
	`get_index_by_number` (number)
	`get_isrc` ()
	`get_language_by_code` (code)
	`get_language_by_index` (index)
	`get_next` ()
	`get_number_of_fragments` ()
	`get_number_of_indices` ()
	`get_number_of_languages` ()
	`get_prev` ()
	`get_sector` (address, abs)
	`get_sector_type` ()
	`get_track_start` ()
	`layout_contains_address` (address)
	`layout_get_length` ()
	`layout_get_session_number` ()
	`layout_get_start_sector` ()
	`layout_get_track_number` ()
	`layout_set_start_sector` (start_sector)
	`layout_set_track_number` (track_number)
	`put_sector` (sector)
	`remove_fragment_by_index` (index)
	`remove_fragment_by_object` (fragment)
	`remove_index_by_number` (number)
	`remove_index_by_object` (index)
	`remove_language_by_code` (code)
	`remove_language_by_index` (index)
	`remove_language_by_object` (language)
	`set_ctl` (ctl)
	`set_flags` (flags)
	`set_isrc` (isrc)
	`set_sector_type` (sector_type)
	`set_track_start` (track_start)

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.Track` 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.Track(**kwargs)¶

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

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

add_fragment(index, fragment)¶

Parameters:

index (int) – index at which fragment should be added
fragment (Mirage.Fragment) – a Mirage.Fragment to be added

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

Currently, unlike in most libMirage’s *_add_* functions, fragment argument cannot be None. This is because specific fragment implementation is required and therefore must be provided by the caller.

Causes bottom-up change.

add_index(address)¶

Parameters:: address (int) – address at which the index is to be added
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Adds index to track.

address is track-relative address at which index should be added. As it determines position of the index, it also determines the number index will be assigned.

If address falls before index 01 (i.e. if it’s less than address that was set using Mirage.Track.set_track_start()), the function fails.

add_language(code, language)¶

Parameters:

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

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Adds language to track.

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

enumerate_fragments(func, *user_data)¶

Parameters:

func (Mirage.EnumFragmentCallback) – 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 fragments list, calling func for each fragment in the layout.

If func returns False, the function immediately returns False.

enumerate_indices(func, *user_data)¶

Parameters:

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

Returns:

True on success, False on failure

Return type:

bool

Iterates over indices list, calling func for each index.

If func returns False, the function immediately returns False.

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.

find_fragment_with_subchannel()¶

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

Retrieves first fragment that contains subchannel data. A reference to fragment is stored in fragment; it should be released with GObject.Object.unref() when no longer needed.

Intended for internal use only.

get_adr()¶

Returns:: ADR value
Return type:: int

Retrieves track’s ADR.

At the moment, ADR is always returned as 1.

get_ctl()¶

Returns:: CTL value
Return type:: int

Retrieves track’s CTL. CTL is calculated on basis of track mode and track flags.

get_flags()¶

Returns:: track flags
Return type:: int

Retrieves track flags.

get_fragment_by_address(address)¶

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

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

get_fragment_by_index(index)¶

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

Retrieves fragment by index. If index is negative, fragments from the end of track 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_index_by_address(address)¶

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

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

get_index_by_number(number)¶

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

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

get_isrc()¶

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

Retrieves ISRC.

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 track 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_next()¶

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 is placed after self in session layout

get_number_of_fragments()¶

Returns:: number of fragments
Return type:: int

Retrieves number of fragments making up the track.

get_number_of_indices()¶

Returns:: number of indices
Return type:: int

Retrieves number of indices the track contains. Note that this includes only indices greater than 01.

get_number_of_languages()¶

Returns:: number of languages
Return type:: int

Retrieves number of languages the track contains.

get_prev()¶

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 is placed before self in session layout.

get_sector(address, abs)¶

Parameters:

address (int) – sector address
abs (bool) – absolute address

Raises:

GLib.Error

Returns:

sector object on success, None on failure. The sector object should be released with GObject.Object.unref() when no longer needed.

Return type:

Mirage.Sector

Retrieves a sector. address is sector address for which a Mirage.Sector object representing sector should be returned. abs specifies whether address is absolute or relative; if True, address is absolute (i.e. relative to start of the disc), if False, it is relative (i.e. relative to start of the track).

A reference to sector is stored in sector; it should be released with GObject.Object.unref() when no longer needed.

get_sector_type()¶

Returns:: sector type
Return type:: Mirage.SectorType

Retrieves type of sectors comprising the track.

get_track_start()¶

Returns:: track start address
Return type:: int

Retrieves track start address. This is track-relative address at which pregap ends and track “logically” starts (i.e. where index changes from 00 to 01).

layout_contains_address(address)¶

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

Checks whether the track contains the given address or not.

layout_get_length()¶

Returns:: track length
Return type:: int

Retrieves track’s length. The returned length is given in sectors.

layout_get_session_number()¶

Returns:: session number
Return type:: int

Retrieves track’s session number. If track is not part of disc layout, 0 is returned.

layout_get_start_sector()¶

Returns:: start sector
Return type:: int

Retrieves track’s start sector.

layout_get_track_number()¶

Returns:: track number
Return type:: int

Retrieves track’s track number.

layout_set_start_sector(start_sector)¶

Parameters:: start_sector (int) – start sector

Sets track’s start sector.

Intended for internal use only.

Causes top-down change.

layout_set_track_number(track_number)¶

Parameters:: track_number (int) – track number

Set track’s track number.

Intended for internal use only.

put_sector(sector)¶

Parameters:: sector (Mirage.Sector) – a Mirage.Sector representing sector to be written
Raises:: GLib.Error
Returns:: True on success, False on failure.
Return type:: bool

Writes the sector to track. The address at which sector is written is retrieved from sector’s property; for this function to succeed, the address must either fall within track’s layout (i.e., the track’s fragment(s) must have sufficient length “reserved” to accept sector), or, alternatively, the sector address is allowed to equal track’s current lenght plus one. In the latter case, the track’s length is incremented when the sector is written (i.e., the corresponding track’s fragment is extended before data is written to it).

remove_fragment_by_index(index)¶

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

Removes fragment from track.

index is the index of the fragment to be removed. This function calls Mirage.Track.get_fragment_by_index() so index behavior is determined by that function.

Causes bottom-up change.

remove_fragment_by_object(fragment)¶

Parameters:: fragment (Mirage.Fragment) – fragment object to be removed

Removes fragment from track.

fragment is a Mirage.Fragment object to be removed.

Causes bottom-up change.

remove_index_by_number(number)¶

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

Removes index from track. This causes index numbers of remaining indices to be readjusted.

number is index number of index to be removed. It must be greater or equal than 2.

remove_index_by_object(index)¶

Parameters:: index (Mirage.Index) – index object to be removed

Removes index from track.This causes index numbers of remaining indices to be readjusted.

index is a Mirage.Index object to be removed.

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

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

index is the index of the language to be removed. This function calls Mirage.Track.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 track.

language is a Mirage.Language object to be removed.

set_ctl(ctl)¶

Parameters:: ctl (int) – track’s CTL

Sets track’s CTL; the function translates CTL into track flags and sets them using Mirage.Track.set_flags(). Track mode set with CTL is ignored.

set_flags(flags)¶

Parameters:: flags (int) – track flags

Sets track flags. flags must be a combination of Mirage.TrackFlags.

set_isrc(isrc)¶

Parameters:: isrc (str) – ISRC

Sets MCN.

Because ISRC is stored in subchannel data, this function silently fails if track contains fragments with subchannel data provided.

set_sector_type(sector_type)¶

Parameters:: sector_type (Mirage.SectorType) – type of sectors comprising the track

Sets sector type. mode must be one of Mirage.SectorType.

set_track_start(track_start)¶

Parameters:: track_start (int) – track start address

Sets track start address. track_start is a track-relative address at which track’s pregap ends and track “logically” starts (i.e. where index changes from 00 to 01). Note that this is not the same as start address that is set by Mirage.Track.layout_set_start_sector(); that one sets the address at which track “physically” starts (i.e. where index 00 starts).

Signal Details¶

Mirage.Track.signals.layout_changed(track)¶

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

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