- Qt 5.15
- Qt Multimedia
- QML Types
- Playlist QML Type
- Qt 5.15.19 Reference Documentation

# Playlist QML Type

For specifying a list of media to be played. More...

Import Statement: | import QtMultimedia 5.15
Since: | Qt 5.6

- List of all members, including inherited members

## Properties

- currentIndex : int
- currentItemsource : url
- error : enumeration
- errorString : string
- itemCount : int
- playbackMode : enumeration
- readOnly : bool

## Signals

- itemAboutToBeInserted(start, end)
- itemAboutToBeRemoved(start, end)
- itemChanged(start, end)
- itemInserted(start, end)
- itemRemoved(start, end)
- loadFailed()
- loaded()

## Methods

- bool addItem(source)
- bool addItems(sources)
- bool clear()
- bool insertItem(index, source)
- bool insertItems(index, sources)
- url itemSource(index)
- load(location, format)
- bool moveItem(from, to)
- next()
- int nextIndex(steps)
- previous()
- int previousIndex(steps)
- bool removeItem(index)
- bool removeItems(int start, int end)
- bool save(location, format)
- shuffle()

## Detailed Description

The Playlist type provides a way to play a list of media with the MediaPlayer, Audio and Video types. It can be used as a data source for view elements (such as ListView) and other elements that interact with model data (such as Repeater). When used as a data model, each playlist item's source URL can be accessed using the `source` role.

     Item {
         width: 400;
         height: 300;

         Audio {
             id: player;
             playlist: Playlist {
                 id: playlist
                 PlaylistItem { source: "song1.ogg"; }
                 PlaylistItem { source: "song2.ogg"; }
                 PlaylistItem { source: "song3.ogg"; }
             }
         }

         ListView {
             model: playlist;
             delegate: Text {
                 font.pixelSize: 16;
                 text: source;
             }
         }

         MouseArea {
             anchors.fill: parent;
             onPressed: {
                 if (player.playbackState != Audio.PlayingState) {
                     player.play();
                 } else {
                     player.pause();
                 }
             }
         }
     }

See also MediaPlayer, Audio, and Video.

## Property Documentation

currentIndex : int

This property holds the position of the current item in the playlist.

currentItemsource : url

This property holds the source URL of the current item in the playlist.

error : enumeration

This property holds the error condition of the playlist.

Value | Description
--- | ---
NoError | No errors
FormatError | Format error.
FormatNotSupportedError | Format not supported.
NetworkError | Network error.
AccessDeniedError | Access denied error.

errorString : string

This property holds a string describing the current error condition of the playlist.

itemCount : int

This property holds the number of items in the playlist.

playbackMode : enumeration

This property holds the order in which items in the playlist are played.

Value | Description
--- | ---
CurrentItemOnce | The current item is played only once.
CurrentItemInLoop | The current item is played repeatedly in a loop.
Sequential | Playback starts from the current and moves through each successive item until the last is reached and then stops. The next item is a null item when the last one is currently playing.
Loop | Playback restarts at the first item after the last has finished playing.
Random | Play items in random order.

readOnly : bool

This property indicates if the playlist can be modified.

## Signal Documentation

itemAboutToBeInserted(start, end)

This signal is emitted when items are to be inserted into the playlist at start and ending at end.

The corresponding handler is `onItemAboutToBeInserted`.

Note: The corresponding handler is `onItemAboutToBeInserted`.

itemAboutToBeRemoved(start, end)

This signal emitted when items are to be deleted from the playlist at start and ending at end.

The corresponding handler is `onItemAboutToBeRemoved`.

Note: The corresponding handler is `onItemAboutToBeRemoved`.

itemChanged(start, end)

This signal is emitted after items have been changed in the playlist between start and end positions inclusive.

The corresponding handler is `onItemChanged`.

Note: The corresponding handler is `onItemChanged`.

itemInserted(start, end)

This signal is emitted after items have been inserted into the playlist. The new items are those between start and end inclusive.

The corresponding handler is `onItemInserted`.

Note: The corresponding handler is `onItemInserted`.

itemRemoved(start, end)

This signal is emitted after items have been removed from the playlist. The removed items are those between start and end inclusive.

The corresponding handler is `onMediaRemoved`.

Note: The corresponding handler is `onItemRemoved`.

loadFailed()

This signal is emitted when the playlist loading failed. error and errorString can be checked for more information on the failure.

The corresponding handler is `onLoadFailed`.

Note: The corresponding handler is `onLoadFailed`.

loaded()

This signal is emitted when the playlist loading succeeded.

The corresponding handler is `onLoaded`.

Note: The corresponding handler is `onLoaded`.

## Method Documentation

bool addItem(source)

Appends the source URL to the playlist.

Returns true if the source is added successfully.

bool addItems(sources)

Appends the list of URLs in sources to the playlist.

Returns true if the sources are added successfully.

This method was introduced in Qt 5.7.

bool clear()

Removes all the items from the playlist.

Returns `true` if the operation is successful.

bool insertItem(index, source)

Inserts the source URL to the playlist at the given index.

Returns true if the source is added successfully.

bool insertItems(index, sources)

Inserts the list of URLs in sources to the playlist at the given index.

Returns true if the sources are added successfully.

This method was introduced in Qt 5.7.

url itemSource(index)

Returns the source URL of the item at the given index in the playlist.

load(location, format)

Loads a playlist from the given location. If format is specified, it is used, otherwise the format is guessed from the location name and the data.

New items are appended to the playlist.

`onloaded()` is emitted if the playlist loads successfully, otherwise `onLoadFailed()` is emitted with error and errorString defined accordingly.

bool moveItem(from, to)

Moves the item at index position from to index position to.

Returns `true` if the item is moved successfully.

This method was introduced in Qt 5.7.

next()

Advances to the next item in the playlist.

int nextIndex(steps)

Returns the index of the item in the playlist which would be current after calling next() steps times.

Returned value depends on the size of the playlist, the current position and the playback mode.

See also playbackMode and previousIndex().

previous()

Returns to the previous item in the playlist.

int previousIndex(steps)

Returns the index of the item in the playlist which would be current after calling previous() steps times.

Returned value depends on the size of the playlist, the current position and the playback mode.

See also playbackMode and nextIndex().

bool removeItem(index)

Removes the item at the given index from the playlist.

Returns `true` if the item is removed successfully.

bool removeItems(int start, int end)

Removes items in the playlist from start to end inclusive.

Returns `true` if the items are removed successfully.

This method was introduced in Qt 5.7.

bool save(location, format)

Saves the playlist to the given location. If format is specified, it is used, otherwise the format is guessed from the location name.

Returns true if the playlist is saved successfully.

shuffle()

Shuffles items in the playlist.