683 lines
16 KiB
Plaintext
683 lines
16 KiB
Plaintext
class Song {
|
|
|
|
%TypeHeaderCode
|
|
#include "core/song.h"
|
|
%End
|
|
|
|
%Docstring
|
|
Contains metadata and information about a music file.
|
|
|
|
Song objects are used throughout Clementine to represent music files and all the
|
|
metadata that goes along with them. A Song contains several groups of
|
|
functions:
|
|
|
|
- The B{constructor} functions L{Init()} and L{InitFromFile()} that are used
|
|
to quickly initialise the contents of a Song, either using the values you
|
|
provide or by reading the tags in a file on disk.
|
|
- The B{getters} such as L{title()} and L{artist()} that return the data
|
|
stored in a Song.
|
|
- The B{setters} such as L{set_title()} and L{set_artist()} that let you
|
|
change metadata in a Song. New metadata isn't written to the actual file
|
|
straight away, you have to call L{Save()} or L{BackgroundSave()} first.
|
|
- The B{pretty getters} such as L{PrettyTitleWithArtist()} that format the
|
|
Song's information in various useful ways.
|
|
|
|
Integer fields in the song like L{track} and L{year} will be C{-1} if they
|
|
don't have a value set.
|
|
|
|
You can get a Song object for the currently playing track by using
|
|
L{Player.GetCurrentItem()} and L{PlaylistItem.Metadata()}:
|
|
|
|
>>> song = clementine.player.GetCurrentItem().Metadata()
|
|
... print song.title()
|
|
|
|
Note that Song objects are dumb containers of information - changing the fields
|
|
in one won't automatically change the information in Clementine's database or
|
|
save the tags to the file. If you want to update information in the database
|
|
such as album art, play count, skip count, rating or whether the song is in a
|
|
compilation, use the methods in L{LibraryBackend}. If you want to save tags
|
|
to a music file, use the L{Save()} or L{BackgroundSave()} methods in this class
|
|
after modifying the relevant fields.
|
|
|
|
Album art for songs in Clementine is split into three different fields -
|
|
L{art_automatic()}, L{art_manual()} and L{image()}. L{art_automatic()} contains
|
|
the art that was found automatically by the library scanner, for example a jpeg
|
|
file in the same directory as the music file. L{art_manual()} contains the art
|
|
that was set manually by the user - if it is present it always takes priority
|
|
over L{art_automatic()}. These fields contain either a string with the filename
|
|
or URL of an image file, or one of two special values - L{kManuallyUnsetCover}
|
|
or L{kEmbeddedCover}. The convenience functions L{has_manually_unset_cover()}
|
|
and L{has_embedded_cover()} check for these special values. L{image()} is a
|
|
special field that is only currently used by radio services that want to
|
|
display the radio station's logo and override the other two C{art_} fields.
|
|
|
|
Some songs are marked as being in a compilation. These songs are shown in the
|
|
special "Various Artists" section in the library. There are three different
|
|
ways a song can be marked as being in a compilation. L{set_compilation()} is
|
|
set by the library scanner when it finds two or more music files in the same
|
|
directory with different artists. L{set_sampler()} is set by L{InitFromFile()}
|
|
if the C{sampler} field in the ID3v2 metadata is present.
|
|
L{set_forced_compilation_on()} and L{set_forced_compilation_off()} are set if
|
|
the user chooses C{Show in various artists} from the right-click menu in the
|
|
Library. The L{is_compilation()} function returns True if the song has been
|
|
marked in any of these ways.
|
|
|
|
@group Class methods: TextForFiletype
|
|
@group Constructors: Init, InitFromFile
|
|
@group Save methods: Save, BackgroundSave
|
|
@group Simple getters: is_valid, id, title, album, artist, albumartist,
|
|
composer, track, disc, bpm, year, genre, comment, is_compilation, rating,
|
|
playcount, skipcount, lastplayed, score, cue_path, has_cue, beginning_nanosec,
|
|
end_nanosec, length_nanosec, bitrate, samplerate, directory_id, filename,
|
|
basefilename, mtime, ctime, filesize, filetype, is_stream, art_automatic, art_manual,
|
|
has_manually_unset_cover, has_embedded_cover, image, url, IsEditable,
|
|
IsMetadataEqual
|
|
@group Pretty getters: PrettyTitle, PrettyTitleWithArtist, PrettyLength,
|
|
PrettyYear, TitleWithCompilationArtist
|
|
@group Simple setters: manually_unset_cover, set_embedded_cover, set_id,
|
|
set_valid, set_title, set_album, set_artist, set_albumartist, set_composer,
|
|
set_track, set_disc, set_bpm, set_year, set_genre, set_genre_id3,
|
|
set_comment, set_compilation, set_sampler, set_beginning_nanosec,
|
|
set_end_nanosec, set_length_nanosec, set_bitrate, set_samplerate, set_mtime,
|
|
set_ctime, set_filesize, set_filetype, set_art_automatic, set_art_manual,
|
|
set_image, set_forced_compilation_on, set_forced_compilation_off, set_rating,
|
|
set_playcount, set_skipcount, set_lastplayed, set_score, set_cue_path,
|
|
set_filename, set_basefilename, set_directory_id
|
|
%End
|
|
|
|
public:
|
|
Song();
|
|
Song(const Song& other);
|
|
|
|
static const QString kManuallyUnsetCover;
|
|
static const QString kEmbeddedCover;
|
|
|
|
enum FileType {
|
|
Type_Unknown,
|
|
Type_Asf,
|
|
Type_Flac,
|
|
Type_Mp4,
|
|
Type_Mpc,
|
|
Type_Mpeg,
|
|
Type_OggFlac,
|
|
Type_OggSpeex,
|
|
Type_OggVorbis,
|
|
Type_Aiff,
|
|
Type_Wav,
|
|
Type_TrueAudio,
|
|
|
|
Type_Stream,
|
|
};
|
|
|
|
static QString TextForFiletype(FileType type);
|
|
%Docstring
|
|
TextForFiletype(type) -> str
|
|
Returns a textual description of one of the C{Type_} constants.
|
|
|
|
Example:
|
|
|
|
>>> print clementine.Song.TextForFiletype(clementine.Song.Type_OggVorbis)
|
|
"Ogg Vorbis"
|
|
%End
|
|
|
|
QString TextForFiletype() const;
|
|
|
|
void Init(const QString& title, const QString& artist, const QString& album, qint64 length_nanosec);
|
|
%Docstring
|
|
Init(title, artist, album, length_nanosec)
|
|
Sets the title, artist, album and length in the Song, and also marks it as
|
|
valid.
|
|
%End
|
|
|
|
void Init(const QString& title, const QString& artist, const QString& album, qint64 beginning, qint64 end);
|
|
void InitFromFile(const QString& filename, int directory_id);
|
|
%Docstring
|
|
InitFromFile(filename, directory_id)
|
|
Loads tags from a music file on disk and marks the Song as valid if it was
|
|
successful.
|
|
|
|
@param directory_id: The ID of the directory containing this Song in the
|
|
L{LibraryBackend}. You can pass -1 to this function to indicate the file is
|
|
not in the library.
|
|
%End
|
|
|
|
bool is_valid() const;
|
|
%Docstring
|
|
is_valid() -> bool
|
|
Flag used to indicate whether an L{InitFromFile()} call returned successfully.
|
|
%End
|
|
|
|
int id() const;
|
|
%Docstring
|
|
id() -> int
|
|
Identifier for this song in the L{LibraryBackend} - C{-1} if this song is not
|
|
from the library.
|
|
%End
|
|
|
|
QString title() const;
|
|
%Docstring
|
|
title() -> str
|
|
%End
|
|
|
|
QString album() const;
|
|
%Docstring
|
|
album() -> str
|
|
%End
|
|
|
|
QString artist() const;
|
|
%Docstring
|
|
artist() -> str
|
|
%End
|
|
|
|
QString albumartist() const;
|
|
%Docstring
|
|
albumartist() -> str
|
|
%End
|
|
|
|
QString composer() const;
|
|
%Docstring
|
|
composer() -> str
|
|
%End
|
|
|
|
int track() const;
|
|
%Docstring
|
|
track() -> int
|
|
%End
|
|
|
|
int disc() const;
|
|
%Docstring
|
|
disc() -> int
|
|
%End
|
|
|
|
float bpm() const;
|
|
%Docstring
|
|
bpm() -> float
|
|
%End
|
|
|
|
int year() const;
|
|
%Docstring
|
|
year() -> int
|
|
%End
|
|
|
|
const QString& genre() const;
|
|
%Docstring
|
|
genre() -> str
|
|
%End
|
|
|
|
const QString& comment() const;
|
|
%Docstring
|
|
comment() -> str
|
|
%End
|
|
|
|
bool is_compilation() const;
|
|
%Docstring
|
|
is_compilation() -> bool
|
|
%End
|
|
|
|
float rating() const;
|
|
%Docstring
|
|
rating() -> float
|
|
The song's user-assigned rating between 0.0 and 1.0.
|
|
%End
|
|
|
|
int playcount() const;
|
|
%Docstring
|
|
playcount() -> int
|
|
Number of times this song has been played by Clementine.
|
|
%End
|
|
|
|
int skipcount() const;
|
|
%Docstring
|
|
skipcount() -> int
|
|
Number of times this song has been skipped by the user pressing Next.
|
|
%End
|
|
|
|
int lastplayed() const;
|
|
%Docstring
|
|
lastplayed() -> int
|
|
The time (in seconds since the epoch) this song was last played by Clementine.
|
|
|
|
You can convert this time to a python C{datetime} object by using
|
|
C{datetime.datetime.fromtimestamp()}.
|
|
%End
|
|
|
|
int score() const;
|
|
%Docstring
|
|
score() -> int
|
|
The automatically generated score assigned to this song based on the
|
|
L{rating()}, L{playcount()} and L{skipcount()}.
|
|
%End
|
|
|
|
const QString& cue_path() const;
|
|
%Docstring
|
|
cue_path() -> str
|
|
If this song was loaded from a cuesheet then this contains the path to the
|
|
cuesheet.
|
|
|
|
@see: L{has_cue()}, L{beginning_nanosec()}, L{end_nanosec()}
|
|
%End
|
|
|
|
bool has_cue() const;
|
|
%Docstring
|
|
has_cue() -> bool
|
|
Whether this song was loaded as part of a cuesheet.
|
|
|
|
@see: L{cue_path()}, L{beginning_nanosec()}, L{end_nanosec()}
|
|
%End
|
|
|
|
qint64 beginning_nanosec() const;
|
|
%Docstring
|
|
beginning_nanosec() -> long
|
|
The index in nanoseconds into the file where this song begins.
|
|
|
|
This is normally 0 except when the song is part of a cuesheet.
|
|
|
|
@see: L{has_cue()}, L{end_nanosec()}
|
|
%End
|
|
|
|
qint64 end_nanosec() const;
|
|
%Docstring
|
|
end_nanosec() -> long
|
|
The index in nanoseconds into the file where this song ends.
|
|
|
|
This is normally 0 except when the song is part of a cuesheet.
|
|
|
|
@see: L{has_cue()}, L{beginning_nanosec()}
|
|
%End
|
|
|
|
qint64 length_nanosec() const;
|
|
%Docstring
|
|
length_nanosec() -> long
|
|
The length of the song in nanoseconds.
|
|
%End
|
|
|
|
int bitrate() const;
|
|
%Docstring
|
|
bitrate() -> int
|
|
%End
|
|
|
|
int samplerate() const;
|
|
%Docstring
|
|
samplerate() -> int
|
|
%End
|
|
|
|
int directory_id() const;
|
|
%Docstring
|
|
directory_id() -> int
|
|
The ID in the L{LibraryBackend} of the directory containing this song, or -1 if
|
|
the song is not from the library.
|
|
%End
|
|
|
|
const QUrl& url() const;
|
|
%Docstring
|
|
url() -> L{PyQt4.QtCore.QUrl}
|
|
The URL of this song.
|
|
%End
|
|
|
|
const QString& basefilename() const;
|
|
%Docstring
|
|
basefilename() -> str
|
|
The filename of this song without any directory component.
|
|
%End
|
|
|
|
uint mtime() const;
|
|
%Docstring
|
|
mtime() -> int
|
|
The time in seconds since the epoch that this song was modified.
|
|
|
|
You can convert this time to a python C{datetime} object by using
|
|
C{datetime.datetime.fromtimestamp()}.
|
|
|
|
@see: L{ctime()}
|
|
%End
|
|
|
|
uint ctime() const;
|
|
%Docstring
|
|
ctime() -> int
|
|
The time in seconds since the epoch that this song was created.
|
|
|
|
You can convert this time to a python C{datetime} object by using
|
|
C{datetime.datetime.fromtimestamp()}.
|
|
|
|
@see: L{mtime()}
|
|
%End
|
|
|
|
int filesize() const;
|
|
%Docstring
|
|
filesize() -> int
|
|
The size of this file in bytes.
|
|
%End
|
|
|
|
FileType filetype() const;
|
|
%Docstring
|
|
filetype() -> FileType
|
|
The type of media file.
|
|
|
|
@see: L{TextForFiletype}
|
|
%End
|
|
|
|
bool is_stream() const;
|
|
%Docstring
|
|
is_stream() -> bool
|
|
True if this song represents a stream (a remote file) and false otherwise.
|
|
%End
|
|
|
|
QString art_automatic() const;
|
|
%Docstring
|
|
art_automatic() -> str
|
|
The filename or URL of automatically discovered album art, or one of the special
|
|
values L{kManuallyUnsetCover} or L{kEmbeddedCover}.
|
|
|
|
@see: L{art_manual()}, L{has_manually_unset_cover()}, L{has_embedded_cover()}
|
|
%End
|
|
|
|
QString art_manual() const;
|
|
%Docstring
|
|
art_manual() -> str
|
|
The filename or URL of album art set by the user, or one of the special
|
|
values L{kManuallyUnsetCover} or L{kEmbeddedCover}.
|
|
|
|
@see: L{art_automatic()}, L{has_manually_unset_cover()}, L{has_embedded_cover()}
|
|
%End
|
|
|
|
bool has_manually_unset_cover() const;
|
|
%Docstring
|
|
has_manually_unset_cover() -> bool
|
|
Returns True if the album art has been manually unset by the user.
|
|
|
|
@see: L{art_manual()}, L{manually_unset_cover()}
|
|
%End
|
|
|
|
void manually_unset_cover();
|
|
%Docstring
|
|
manually_unset_cover()
|
|
Marks this song as having a manually unset album cover.
|
|
|
|
@see: L{art_manual()}, L{has_manually_unset_cover()}
|
|
%End
|
|
|
|
bool has_embedded_cover() const;
|
|
%Docstring
|
|
has_embedded_cover() -> bool
|
|
Returns True if the album art is embedded within the file.
|
|
|
|
@see: L{art_automatic()}, L{set_embedded_cover()}
|
|
%End
|
|
|
|
void set_embedded_cover();
|
|
%Docstring
|
|
set_embedded_cover()
|
|
Marks this song as having album art contained within it.
|
|
|
|
@see: L{art_automatic()}, L{has_embedded_cover()}
|
|
%End
|
|
|
|
QImage image() const;
|
|
%Docstring
|
|
image() -> L{PyQt4.QtGui.QImage}
|
|
An album art image that overrides L{art_automatic()} and L{art_manual()}.
|
|
%End
|
|
|
|
// Pretty accessors
|
|
QString PrettyTitle() const;
|
|
%Docstring
|
|
PrettyTitle() -> str
|
|
Returns the title of this song if it is set, or else returns the filename.
|
|
%End
|
|
|
|
QString PrettyTitleWithArtist() const;
|
|
%Docstring
|
|
PrettyTitleWithArtist() -> str
|
|
Returns "artist - title" if both are set, otherwise returns L{PrettyTitle()}.
|
|
%End
|
|
|
|
QString PrettyLength() const;
|
|
%Docstring
|
|
PrettyLength() -> str
|
|
Returns the length of the song formatted as "(hh:)mm:ss".
|
|
%End
|
|
|
|
QString PrettyYear() const;
|
|
%Docstring
|
|
PrettyYear() -> str
|
|
Returns the year if it is set, otherwise returns "".
|
|
%End
|
|
|
|
QString TitleWithCompilationArtist() const;
|
|
%Docstring
|
|
TitleWithCompilationArtist() -> str
|
|
If this song is part of a compilation B{and} the artist is B{not} "Various
|
|
Artists", returns L{PrettyTitleWithArtist()}, otherwise returns L{PrettyTitle()}.
|
|
%End
|
|
|
|
// Setters
|
|
bool IsEditable() const;
|
|
%Docstring
|
|
IsEditable() -> bool
|
|
Returns True if this song is backed by a local file that is writable and is not
|
|
part of a cue sheet.
|
|
%End
|
|
|
|
bool Save() const;
|
|
%Docstring
|
|
Save() -> bool
|
|
Saves the metadata to the file and returns True if it was successful.
|
|
|
|
@warning: This method is B{blocking} and should not be called from the main
|
|
thread. Use the L{BackgroundSave()} method instead which works in a
|
|
background thread.
|
|
%End
|
|
|
|
void BackgroundSave() const;
|
|
%Docstring
|
|
BackgroundSave()
|
|
Saves the metadata to the file in a background thread and returns immediately.
|
|
%End
|
|
|
|
void set_id(int id);
|
|
%Docstring
|
|
set_id(id)
|
|
%End
|
|
|
|
void set_valid(bool v);
|
|
%Docstring
|
|
set_valid(valid)
|
|
%End
|
|
|
|
void set_title(const QString& v);
|
|
%Docstring
|
|
set_title(title)
|
|
%End
|
|
|
|
|
|
void set_album(const QString& v);
|
|
%Docstring
|
|
set_album(album)
|
|
%End
|
|
|
|
void set_artist(const QString& v);
|
|
%Docstring
|
|
set_artist(artist)
|
|
%End
|
|
|
|
void set_albumartist(const QString& v);
|
|
%Docstring
|
|
set_albumartist(albumartist)
|
|
%End
|
|
|
|
void set_composer(const QString& v);
|
|
%Docstring
|
|
set_composer(composer)
|
|
%End
|
|
|
|
void set_track(int v);
|
|
%Docstring
|
|
set_track(track)
|
|
%End
|
|
|
|
void set_disc(int v);
|
|
%Docstring
|
|
set_disc(disc)
|
|
%End
|
|
|
|
void set_bpm(float v);
|
|
%Docstring
|
|
set_bpm(bpm)
|
|
%End
|
|
|
|
void set_year(int v);
|
|
%Docstring
|
|
set_year(year)
|
|
%End
|
|
|
|
void set_genre(const QString& v);
|
|
%Docstring
|
|
set_genre(genre)
|
|
%End
|
|
|
|
void set_genre_id3(int id);
|
|
%Docstring
|
|
set_genre_id3(id)
|
|
Sets the genre from an ID3v1 genre ID. See
|
|
U{Appendix A of the ID3v1 specification<http://www.id3.org/id3v2.3.0#head-129376727ebe5309c1de1888987d070288d7c7e7>}.
|
|
%End
|
|
|
|
void set_comment(const QString& v);
|
|
%Docstring
|
|
set_comment(comment)
|
|
%End
|
|
|
|
void set_compilation(bool v);
|
|
%Docstring
|
|
set_compilation(compilation)
|
|
%End
|
|
|
|
void set_sampler(bool v);
|
|
%Docstring
|
|
set_sampler(sampler)
|
|
%End
|
|
|
|
void set_beginning_nanosec(qint64 v);
|
|
%Docstring
|
|
set_beginning_nanosec(nanosec)
|
|
%End
|
|
|
|
void set_end_nanosec(qint64 v);
|
|
%Docstring
|
|
set_end_nanosec(nanosec)
|
|
%End
|
|
|
|
void set_length_nanosec(qint64 v);
|
|
%Docstring
|
|
set_length_nanosec(nanosec)
|
|
%End
|
|
|
|
void set_bitrate(int v);
|
|
%Docstring
|
|
set_bitrate(bitrate)
|
|
%End
|
|
|
|
void set_samplerate(int v);
|
|
%Docstring
|
|
set_samplerate(samplerate)
|
|
%End
|
|
|
|
void set_mtime(int v);
|
|
%Docstring
|
|
set_mtime(mtime)
|
|
%End
|
|
|
|
void set_ctime(int v);
|
|
%Docstring
|
|
set_ctime(ctime)
|
|
%End
|
|
|
|
void set_filesize(int v);
|
|
%Docstring
|
|
set_filesize(size)
|
|
%End
|
|
|
|
void set_filetype(FileType v);
|
|
%Docstring
|
|
set_filetype(type)
|
|
%End
|
|
|
|
void set_art_automatic(const QString& v);
|
|
%Docstring
|
|
set_art_automatic(art)
|
|
%End
|
|
|
|
void set_art_manual(const QString& v);
|
|
%Docstring
|
|
set_art_manual(art)
|
|
%End
|
|
|
|
void set_image(const QImage& i);
|
|
%Docstring
|
|
set_image(image)
|
|
%End
|
|
|
|
void set_forced_compilation_on(bool v);
|
|
%Docstring
|
|
set_forced_compilation_on(compilation)
|
|
%End
|
|
|
|
void set_forced_compilation_off(bool v);
|
|
%Docstring
|
|
set_forced_compilation_off(compilation)
|
|
%End
|
|
|
|
void set_rating(float v);
|
|
%Docstring
|
|
set_rating(rating)
|
|
%End
|
|
|
|
void set_playcount(int v);
|
|
%Docstring
|
|
set_playcount(playcount)
|
|
%End
|
|
|
|
void set_skipcount(int v);
|
|
%Docstring
|
|
set_skipcount(skipcount)
|
|
%End
|
|
|
|
void set_lastplayed(int v);
|
|
%Docstring
|
|
set_lastplayed(lastplayed)
|
|
%End
|
|
|
|
void set_score(int v);
|
|
%Docstring
|
|
set_score(score)
|
|
%End
|
|
|
|
void set_url(const QUrl& v);
|
|
%Docstring
|
|
set_url(url)
|
|
%End
|
|
|
|
void set_basefilename(const QString& v);
|
|
%Docstring
|
|
set_basefilename(basefilename)
|
|
%End
|
|
|
|
void set_directory_id(int v);
|
|
%Docstring
|
|
set_directory_id(directory_id)
|
|
%End
|
|
|
|
void set_cue_path(const QString& v);
|
|
%Docstring
|
|
set_cue_path(cue_path)
|
|
%End
|
|
|
|
bool IsMetadataEqual(const Song& other) const;
|
|
%Docstring
|
|
IsMetadataEqual(other) -> bool
|
|
Compares the metadata (not including ratings, playcounts, etc) with another
|
|
Song and returns true if they are equal.
|
|
%End
|
|
};
|
|
typedef QList<Song> SongList;
|