Song Tracker

This module provides a tracker to track songs and videos that were streamed. The goal of the tracker is to collect information which songs and videos can be played in series. So the relation between two songs or videos gets stored in a database - the Tracker Database. The user can then get the information which song/video were played after (or before) a specific song/video.

The Tracker consists of the following parts:

  • The Tracker class (Tracker) tracking music with an internal queue that holds the last played song or and video.

  • The Tracker Database (TrackerDatabase) that stores the tracked music relations.

Example

# Dependencies
cfg = MusicDBConfig("./musicdb.ini")

# Create a new tracker
tracker = SongTracker(cfg)
tracker.AddSong("Unicorn/2000 - Honey Horn/13 Rainbow Song.mp3")
tracker.AddSong("Truther/2013 - Real Album/23 Illuminati.mp3")

Tracker Class

class musicdb.mdbapi.tracker.Tracker(config, target)[source]

This class tracks music (songs and videos) that were played after each other. So it gets tracked what songs or videos the user put together into the queue because their style fit to each other.

Only completely played music should considered. Skipped music should be ignored.

Warning

It tracks the played songs and videos using a local state. Creating a new instance of this class also creates a further independent tracker. This could mess up the database with relations that were counted twice!

Note

For better readability it is recommended to use the derived classes SongTracker and VideoTracker.

Parameters:

  • config – MusicDBConfig object holding the MusicDB Configuration

  • target (str) – "song" or "video" depending what kind of music will be tracked

Raises:

  • TypeError – When the arguments are not of the correct type.

  • ValueError – When target is not "song" or "video"

Track(targetid, israndom=False)[source]

This method tracks the relation to the given target with the last added target. It also tracks when music was played. A target can be a song or a video. This new target should be a target that was recently and completely played.

The played music will always be tracked via musicdb.lib.db.trackerdb.TrackerDatabase.AddMusic().

Additional, under certain conditions, the chain of consecutive played music gets tracked. This process is described in the following paragraphs.

If the time between this target, and the previous one exceeds N minutes, it gets ignored and the internal state gets reset. So the chain of targets get cut if the time between playing them is too long. The amount of time until this cut takes place can be configured: MusicDB Configuration The chain of targets gets also cut, if targetid is None or invalid.

If the given target is the same as the last target, then it gets ignored.

The israndom parameter indicates if a target got added by the randomizer into the queue. The behavior of the tracker then depends on the [tracker]->trackrandom settings. If israndom and trackrandom are both True, the music gets tracked as if it was added by the user. If trackrandom is False, randomly added music gets not tracked. Anyway, the chain will not be cut. So the next music continues the chain.

After adding a target, the method checks for a new relation between two targets. This is the case when there was previously a target added.

The relation gets added to the tracker database by calling musicdb.lib.db.trackerdb.TrackerDatabase.AddRelation()

Parameters:

  • targetid – ID of the song or video that gets currently played, None to cut the chain of consecutive targets.

  • israndom (bool) – True indicates that the music was added by the random song selection algorithm Randy.

Returns:

True on success. False in case an error occurred.

Tracker Database

This module is used to manage the Tracker Database.

There are two tables of each kind, one for song relations and one for video relations.

Because the tables contain similar information, their data and algorithms are similar. All methods are made to work on all tables. The parameter target is either "song" or "video" and distinguish the tables. If the documentation mentions targetid it either is the term songid or videoid depending on the argument of the method.

This classes uses a global lock (using Python threading.RLock) to avoid that relations change during complex operation.

Music Relation Chain

The database stores the relation between two songs or videos. That means, whenever two songs or videos were played after each other, this relation gets created or its weight incremented.

The tables layout is the following:

id

targetida

targetidb

weight
id:

ID of the row

targetida / targetidb:

IDs of the songs or videos that were played together. ID A is the smaller number of the two: targetida < targetidb. There will not be the situation where targetida and targetidb have the same ID. It is prevented by the method creating the relation.

weight:

Gets incremented whenever the targetida/targetidb relation already occurred in the past.

Music Played History

The tracker database also stores when a song or video was played.

id

targetid

timestamp

random
id:

ID of the row

targetid:

Actually songid or videoid stores the ID of the song or video that gets tracked.

timestamp:

When the song or video got played as unix time stamp

random:

True when the song got added by the random song selection algorithm, otherwise False

TrackerDatabase Class

class musicdb.lib.db.trackerdb.TrackerDatabase(path)[source]

Derived from musicdb.lib.db.database.Database.

Parameters:

path (str) – Absolute path to the tracker database file.

Raises:

ValueError – When the version of the database does not match the expected version. (Updating MusicDB may failed)

AddMusic(target, targetid, timestamp, random)[source]

This method adds music to the played history. A target can be a song or a video.

Parameters:

  • target (str) – "song" or "video"

  • targetid (int) – Song ID or Video ID, depending on the target string

  • timestamp (int) – Unix time when the song or video was played

  • random (boolean) – True when the music was added by the random song selection algorithm

Returns:

None

Raises:

  • ValueError – If target not "song" or "video"

  • TypeError – If targetid or timestamp is not of type int

  • TypeError – If random is not of type bool

AddRelation(target, ida, idb)[source]

This method adds a relation between two targets. A target can be a song or a video.

It does not matter which one is greater, ida or idb. This gets handled automatically. If ida and idb are the same ID, they get ignored.

Parameters:

  • target (str) – "song" or "video"

  • ida (int) – Song ID or Video ID, depending on the target string

  • ida – Song ID or Video ID, depending on the target string

Returns:

None

Raises:

  • ValueError – If target not "song" or "video"

  • TypeError – If ida or idb is not of type int

GetRelations(target, targetid)[source]

This method returns the related songs or videos of a song or a video, depending on the value of target.

The method returns a list of dictionaries. Each dictionary contains the ID of the related song or video, and the weight of the relation.

Parameters:

  • target (str) – song or video

  • targetid (int) – Song ID or Video ID, depending on the target string

Returns:

List of relations. The list is empty if there are no relations

Raises:

  • ValueError – If target not "song" or "video"

  • TypeError – If targetid is not of type int

Example

relations = trackerdatabase.GetRelations("song", 1000)
for r in relations:
    print("Related song ID: %d; Weight: %d"%(r["id"], r["weight"]))
RemoveRelation(target, ida, idb)[source]

This method removes a relation between two targets. A target can be a song, a video or a video.

It does not matter which one is greater, ida or idb. This gets handled automatically. If ida and idb are the same ID, they get ignored.

Parameters:

  • target (str) – "song", "video"

  • ida (int) – Song ID or Video ID, depending on the target string

  • ida – Song ID or Video ID, depending on the target string

Returns:

None

Raises:

  • ValueError – If target not "song" or "video"

  • TypeError – If ida or idb is not of type int

RemoveSong(songid)[source]

This method removes all relations to a song. It also removed the song from the played songs table. This is useful in case a song gets removed from the database.

If the song relation does not exist, nothing will be done.

Parameters:

songid (int) – ID of the song

Returns:

None

Raises:

TypeError – Invalid song ID type

RemoveVideo(videoid)[source]

This method removes all relations to a video. It also removed the video from the played videos table. This is useful in case a video gets removed from the database.

If the video relation does not exist, nothing will be done.

Parameters:

videoid (int) – ID of the video

Returns:

None

Raises:

TypeError – Invalid video ID type