1
class PlaylistParser : QObject {
3
#include "playlistparsers/playlistparser.h"
7
Utility class to read and write playlist files.
9
The PlaylistParser supports a number of different playlist formats - these are
10
implemeted by subclasses of L{ParserBase}. Usually you don't need to worry
11
about finding the right parser for your file - PlaylistParser will do that
12
automatically based on the filename you give it (for example, it will use the
13
PlsParser if you ask it to load a file called C{playlist.pls}).
15
If you don't know the filename because you're reading data directly from the
16
network, PlaylistParser can also guess the type of parser to use by looking for
17
magic strings in the first few bytes of the file. The constant C{kMagicSize}
18
tells you how many bytes the PlaylistParser will take when using magic.
20
PlaylistParser deals with loading and saving lists of L{Song} objects.
22
>>> parser = clementine.PlaylistParser(clementine.library)
23
... songlist = parser.LoadFromFile("songs.xspf")
24
... print songlist[0].title()
25
... parser.Save(songlist, "songs.asx")
27
Notice that this class' constructor takes a L{LibraryBackend}. Why does a
28
playlist parser need access to the library? When loading a list of songs the
29
parser will check whether a song exists already in the library, and will use
30
the metadata that's already been loaded instead of loading it again. You can
31
get Clementine's library by using C{clementine.library}.
33
@warning: The L{LoadFromFile()}, L{LoadFromDevice()} and L{Save()} methods in
34
this class are B{blocking} and should not be called from the main thread.
35
For a higher level interface to loading songs from playlists you should use
36
the L{SongLoader} class which works in a background thread.
40
PlaylistParser(LibraryBackend* library, QObject* parent /TransferThis/ = 0);
42
static const int kMagicSize;
44
QStringList file_extensions() const;
46
file_extensions() -> list of str
47
Returns the list of file extensions that the PlaylistParser knows how to parse.
50
QString filters() const;
53
Returns a filter string suitable for use in L{PyQt4.QtGui.QFileDialog}.
56
QString default_extension() const;
58
default_extension() -> str
59
Returns the recommended extension to use when saving playlists. Currently this
63
QString default_filter() const;
65
default_filter() -> str
66
Returns the recommended default filter string suitable for use in
67
L{PyQt4.QtGui.QFileDialog}.
70
ParserBase* ParserForMagic(const QByteArray& data,
71
const QString& mime_type = QString()) const;
73
ParserForMagic(data, mime_type="") -> L{ParserBase}
74
Tries to guess the file type of a playlist based on the first few bytes of its
75
contents or (optionally) a mime type.
77
@param data: should be at least L{kMagicSize} bytes long.
79
@param mime_type: (optional) the mime type of the data obtained through (for
80
example) and HTTP response header.
82
@return: a parser for this file format, or None if it was not possible to guess.
84
@note: only use this method if you need direct access to the parser. If you
85
just want to load a list of songs from some data use L{LoadFromDevice()}.
88
ParserBase* ParserForExtension(const QString& suffix) const;
90
ParserForExtension(suffix) -> L{ParserBase}
91
Tried to guess the file type of a playlist based on its file extension.
93
@param suffix: the file extension, not including the C{.} character.
95
@return: a parser for this file format, or None if the extension wasn't
98
@note: only use this method if you need direct access to the parser. If you
99
just want to load a list of songs from a file use L{LoadFromFile()}.
102
SongList LoadFromFile(const QString& filename) const;
104
LoadFromFile(filename) -> list of L{Song}
105
Loads a playlist from a file and returns the list of songs that it contained.
106
Determines the type of the playlist based on the file extension by calling
107
L{ParserForExtension}.
109
@return: the list of songs in the playlist, or an empty list if the playlist
113
SongList LoadFromDevice(QIODevice* device, const QString& path_hint = "",
114
const QDir& dir_hint = QDir()) const;
116
LoadFromDevice(device, path_hint="", dir_hint="") -> list of L{Song}
117
Loads a playlist from a L{PyQt4.QtCore.QIODevice} and returns the list of songs
118
that it contained. Determines the type of the playlist by peeking at the first
119
L{kMagicSize} bytes of the device and using L{ParserForMagic}.
121
@param device: an open device on a playlist file. You can use any device here,
122
including L{PyQt4.QtNetwork.QTcpSocket}, L{PyQt4.QtCore.QFile} or
123
L{PyQt4.QtCore.QBuffer}.
124
@type device: L{PyQt4.QtCore.QIODevice}
125
@param path_hint: (optional) the filename of the playlist. Some parsers may
126
use this filename to add additional information to the L{Song}s returned, for
127
example the cue parser fills out the L{Song.cue_path()} field.
129
@param dir_hint: (optional) the directory containing the playlist. Parsers will
130
use this directory to resolve any relative filenames in the playlist.
131
@type dir_hint: L{PyQt4.QtCore.QDir}
132
@return: the list of songs in the playlist, or an empty list if the playlist
136
void Save(const SongList& songs, const QString& filename) const;
138
Save(songs, filename)
139
Saves a list of songs to a new playlist. Determines the type of the playlist
140
to create based on the file extension by calling L{ParserForExtension}.
142
@type songs: list of L{Song}
added
removed
src/scripting/python/playlistparser.sip
