TrackStat plugin
From SqueezeboxWiki
Overview
This is a statistic plugin for SqueezeCenter(formerly known as Slimserver). SqueezeCenter normally stores statistics about the last time a track was played, when a specific track was added to the library and how many times a track has been played. The problem is that all this statistics is cleared every time you perform a full rescan of SqueezeCenter. To me this makes the statistics useless since I need to perform rescans from time to time.
The TrackStat plugin solves this problem by making sure that the statistics survives a rescan. This is the core functionality of the TrackStat plugin and the reason I wrote it. Besides this TrackStat also extends the statistics a bit, one example is that it doesn't count a track as played just because you listen to the first 2 seconds of it, you will have to play a certain amount of the track until it is played. TrackStat also makes it possible to put a rating on all your tracks by holding a number between 1-5 down on the now playing screen.
The other main functionality the TrackStat plugins provides is various ways to browse your music based on the statistic information. The standard SqueezeCenter only makes it possible to show most played tracks. The TrackStat plugin makes it possible to show the statistics in a lot more ways. The purpose is simply to give you another way to select which music you like to play, for example like:
- Find tracks you haven't played for a long time
- Find tracks you have recently added to the library
- Find top rated tracks
- Find least played tracks
- And a lot more...
Browsing the statistics is one thing but TrackStat also integrates with the Dynamic Playlist plugin and provides a number of different random playlists where the ordering prioritize different tracks based on the different statistic information. The advantage of dynamic playlists is that new tracks are added to the playlist continously based on the statistics at the time.
Installation
- Remove any previous version of TrackStat from the SqueezeCenter Plugins directory if you have manually installed it earlier (this is not needed if you have installed it through Extension Downloader)
- Goto SqueezeCenter Settings/Plugins and select to install TrackStat. You might need to add Erland's repository to see it, see here for more information regarding this: SqueezeCenter_Repositories. If you don't want to install it through Extension Downloader, you can also download it from the download page and manually unzip the new version in the SqueezeCenter Plugins directory
- Please note that earlier versions of this plugin will require you to also install the License Manager plugin.
- Please note that earlier versions of this plugin will require you to purchase a license.
- Optionally install other plugins that extends TrackStat with more functionality
- Dynamic Playlist plugin
- Custom Scan plugin if you like to use the iTunes, MusicIP or Amarok export/import functionality
- MusicInfoSCR plugin (To display ratings on SqueezeBox display)
- When you have installed everything you might also want to look at:
- Setup support for ratings (Includes description about how to setup rating/statistics synchronization with iTunes/MusicIP)
Note!
- More information about how to purchase and activate the commercial license can be found through the License Manager plugin
If you are using SlimServer 6.5 and earlier, you may want to use the old guide instead
Upgrade/Reinstall
The following describes the process to upgrade Squeezebox Server to a new major version or re-install Squeezebox Server on a new computer and make sure that your statistics is copied properly.
Backup statistics before upgrade/reinstall
Do the following in the old Squeezebox Server installation before upgrading/reinstalling.
- Goto Squeezebox Server Settings -> Advanced -> TrackStat -> Backup/Restore/Clear
- Specify the full path to a file where you want the backup to be stored in the "Backup file" parameter
- Click "Apply" to save the settings.
- Click the "Backup to file" button to perform the backup
- If you like to be 100% sure to not loose anything, you can double check that the backup file seems to contain TrackStat data by looking at its size or viewing it in a text editor.
- Make sure the backup file is stored in a safe place
Restore statistics after upgrade/reinstall
In the new Squeezebox Server installation after upgrading/reinstalling.
- Let Squeezebox Server complete the rescan so all your music is available, a TrackStat backup can't be restored before the rescan has completed successfully.
- Goto Squeezebox Server Settings -> Advanced -> TrackStat -> Backup/Restore/Clear
- Specify the full path to the file with TrackStat data in the "Backup file" parameters. If you performed the manual backup in previous installation on the same computer this is probably already set correctly.
- If you know your current TrackStat data from previous installation was correct, it's a good idea to set "Find alternative files" option to "No" as that will make the restore considerably faster. Setting this to "Yes" will make the restore extremely slow in some setups.
- Click "Apply" to save the settings.
- Click "Remove all data" button to remove any default data which was generated due to the Squeezebox Server rescan. This step is optional and isn't needed in all setups, but I'd recommend doing it to get as clean TrackStat data as possible.
- Click "Restore from file" button to start the restore. The restore operation will continue in the background, you have to look in the server.log file to see when it's finished.
The server.log will indicate with a message like this when the restore has started:
Restore from: /home/xxx/TrackStat/trackstat_scheduled_backup_20110706.xml
And with a message like this when the backup has been successfully restored:
Restore completed at 2011-07-06 12:13:20
If you accidentally shutdown Squeezebox Server before the restore is finished, you will have to repeat the operation. As reference, in a 3500 song library on a typical computer it might take about 8 minutes to restore the backup.
Bugs and new features
The current list of known bugs and wishes for new features can be found here:
If you want to encourage future development of this plugin you should purchase a license or consider making a donation
Issues with duplicate musicbrainz tags
Musicbrainz previously represented a unique track identity but a few years back Musicbrainz changed the definition to represent a song instead of a recording. The result is that today a song on a compilation typically get the same identity as a song on a normal album and this causes problem for TrackStat.
To identity if this is a problem in your library, the easiest way is to install the Database Query plugin and run its "Squeezebox Server Inconsistency/Problems" and "TrackStat Inconsistency/Problems" reports. If the "TrackStat Inconsistency/Problems" report indicates "Duplicate entries in TrackStat statistics" and "Squeezebox Server Inconsistency/Problems" indicates "Duplicate musicbrainz song tags" it means that you are affected. In this case you either need to remove the musicbranz tags from the problematic files or you have to disable Musicbrainz support in TrackStat. Below follows more information how to solve the problem and remove the duplicates.
As long as you have a TrackStat backup you shouldn't loose anything with the below procedure, but if you want to be 100% sure you can always also shutdown LMS and take a backup of the persist.db and library.db files in the LMS Cache directory as this is where the TrackStat information is stored. If something doesn't work, you can always shutdown LMS and restore these files to get back to the current situation. It's important to shutdown LMS before you copy or restore these files manually.
- Make a TrackStat backup, see "Backup statistics before upgrade/reinstall" section
- Disable musicbrainz tags in TrackStat settings page through Settings -> Advanced -> TrackStat and set the "Enable musicbrainz tags" option to "No"
- Perform a full rescan in LMS and wait for it to complete
- Clear all TrackStat data through Settings -> Advanced -> TrackStat -> Backup/Restore/Clear and its "Remove all data" option. This step is important since it's the one that's going to remove the duplicates.
- Restore the backup from point 1, see "Restore statistics after upgrade/reinstall" secton
Also note that the restore process is executed in the background and will produce a message in the server.log file when it's finished. If you have a large library it can take some time so don't worry if the statistics aren't shown directly after you have clicked the "Restore from file" button.
iTunes integration
TrackStat provides an integration with iTunes. The standard SqueezeCenter iTunes integration makes it possible get available tracks from iTunes and also retrieves the rating, play counts and played time information. The TrackStat iTunes integration provides the following main functionalities:
- Import of ratings, play counts and played time for tracks that already exists in SqueezeCenter, basically the same as the standard SqueezeCenter iTunes integration
- Export of ratings, play counts and played time for all tracks in SqueezeCenter. The export is done through a text file which will have to be feed into iTunes using a provided perl script.
- The Import and Export functionality also provides a way to map file paths. This means that the TrackStat iTunes integration can be used in a situation where you have FLAC format on all music in SqueezeCenter and MP3 in iTunes. It also works in a configuration where SqueezeCenter runs on Linux and iTunes on Windows.
- Possibility to log information about changed ratings, play counts, played time on tracks in SqueezeCenter as they are played. This log file can be feed into iTunes using a provided perl script. The result is that you can easily have SqueezeCenter as your statistic source and update the iTunes database with latest statistics at regular intervals.
- If you have the Multi Library plugin installed you will also get some options to limit the export/import to selected libraries defined in the Multi Library plugin
- The import/export functionality is found under the Custom Scan menu inside SqueezeCenter Settings in the web interface.
MusicIP integration
TrackStat provides an integration with MusicIP. The standard SqueezeCeneter MusicIP integration makes it possible to get available tracks from MusicIP and also retrieves the rating, play counts and played time information. The TrackStat MusicIP integration provides the following main functionalities:
- Import of ratings, play counts and played time for tracks that already exists in SqueezeCenter basically the same as the standard SqueezeCenter MusicIP integration.
- Export of ratings, play counts and played time for all tracks in SqueezeCenter.
- The Import and Export functionality also provides a way to map file paths. This mean that the TrackStat MusicIP integration can be used in a situation where you have FLAC format on all music in SqueezeCeneter and MP3 in MusicIP. It also works in a configuration where SqueezeCenter runs on a Linux and MusicIP on Windows.
- When you change a rating or play a track in SqueezeCeneter it will also dynamically be sent to MusicIP so the statistic information in MusicIP always are up to date.
- If you have the Multi Library plugin installed you will also get some options to limit the export/import to selected libraries defined in the Multi Library plugin
- The import/export functionality is found under the Custom Scan menu inside SqueezeCenter Settings in the web interface.
Amarok integration
TrackStat provides an integration with Amarok. The TrackStat Amarok integration provides the following main functionalities:
- Import of ratings, play counts and played time from Amarok for tracks that already exists in SqueezeCenter.
- Export of ratings, play counts added time and played time to Amarok for all tracks in SqueezeCenter.
- The Import and Export functionality also provides a way to map file paths. This mean that the TrackStat Amarok integration can be used in a situation where you have FLAC format on all music in SqueezeCenter and MP3 in Amarok. It also works in a configuration where SqueezeCenter runs on a one computer and Amarok on another computer.
- When you change a rating or play a track in SqueezeCenter it will also dynamically be sent to Amarok so the statistic information in Amarok always are up to date.
- The TrackStat Amarok integration only works together with Amarok using MySQL. It has not been tested together with Amarok using the default SQLite database.
- If you have the Multi Library plugin installed you will also get some options to limit the export/import to selected libraries defined in the Multi Library plugin
- The import/export functionality is found under the Custom Scan menu inside SqueezeCenter Settings in the web interface.
Persistent storage and backup of statistics
Normally in SqueezeCenter all statistics are clear when you perform a full rescan, there is also no way to take a backup of just the statistic data which can be restored after the rescan. TrackStat provides functionality in this area in a number of ways:
- It is possible to manually backup and restore statistic data.
- It is possible to automatically turn on nightly backup of statistic data every night, note that this requires that your computer is powered on. A new backup file will be created every night if this functionality is enabled. Note! There is currently no clean up functionality that removes old backup files, so you will have to do this manually once per month or year to make sure your disk isn't filled with backup files.
- TrackStat stores the statistic information in a separate table in the database, the result is that statistic data will automatically survive a full rescan of SqueezeCenter. If you have MusicBrainz tags in your music it will even survive a situation where you have moved or renamed your music files, without MusicBrainz tag only statistics for unmoved files with the same name as before will survive.
Display of ratings
The normal SqueezeCeneter display ratings in the Web interface in the "Song info" page. TrackStat extends this by making it possible to also display ratings in all track listings both in web interface and on the SqueezeBox/Transporter display. TrackStat does this by defining a number of new title formats which you can select to show in the track listings. The following title formats are supported:
- TRACKSTATRATINGDYNAMIC - Shows the rating as a dynamic number of characters, a rating of 3 is displayed as (_ is shown here instead of spaces): "_*_*_*"
- TRACKSTATRATINGSTATIC - Shows the rating as static number of characters, a rating of 3 is displayed as (_ is shown here instead of spaces): "_*_*_*____" (Note the spaces at the end)
- TRACKSTATRATINGNUMBER - Shows the rating as a digit, a rating of 4 is displayed as "4"
To configure SqueezeCenter to show the ratings you will need to configure the display formatting attributes, this is done as follows:
- Goto "SqueezeCeneter Settings / Formatting" in the web interface
- Step down to the "TITLE FORMAT" setting. Here you select which title format that shall be used in the web interface and you also select which title formats that shall be available to select on the SqueezeBox/Transporter display. TrackStat has already added a number of different title formats that contains the above mentioned keywords. You can either compose your own title format using the existing keywords or select one of the existing ones. Note that even though you aren't going to use a title format in the web interface it needs to exist here if you like to use it on the SqueezeBox/Transporter display.
- Click the Change button to save your changes
- Goto "Player Settings" for the SqueezeBox/Transporter in the web interface.
- Step down to the "TITLE FORMAT" settings. Here you can select which title formats that shall be available to toggle between on the SqueezeBox/Transporter display and also select the one that shall be active by default.
- Click the Change button to save your changes
Note that to fully customize the display on the SqueezeBox/Transporter I recommend that you also install the MusicInfoSCR plugin. This will make it possible to customize exactly what should be shown on both display rows, as an example you can put the rating information on the upper row and still just have the track, artist album information on the button row as usual.
Automatically change ratings
By default ratings in TrackStat is only changed when the user choose to change the rating. You can optionally turn on the "Automatic rating" option in "Server Settings/Plugins/TrackStat". If you turn on automatic ratings the ratings of the songs will be automatically changed based on if you listen through a whole song or skip it directly. If you skip a song in the beginning the rating will be decreased, if you listen through almost the whole song the rating will be increased. If the "Dynamic automatic ratings" option also found in "Server Settings/Plugins/TrackStat" also is enabled, ratings will be increased/decreased faster when the rating is around 3 stars and slower when the rating is around 1 or 5 stars.
Available statistics
The TrackStat plugin stores the following different statistic information:
- Rating
- The last time a song was played
- The number of time a song has been played
- The time a song was added to SqueezeCenter
- A history log of exactly when each song has been played or rated
Note also that there is a difference compared to SqueezeCenter when a song is detected as it has been played. Standard SqueezeCenter detect a song as played as soon as you have played it even though you just played the first second and skipped to the next song directly. TrackStat improves this by only counting a song as played if the following criterias are true:
- The song is longer than 5 second
- At least 50% of the song has been played unless the song is longer than 30 minutes
The exact value of the above criterias are configurable in the TrackStat settings page. The value of having them is that you can safely skipping a song without increasing the play count, this is important for statistics like "Most played songs" to be really valuable.
Browsing the statistics
The statistics managed by the TrackStat plugin can be browsed either from the TrackStat web interface or from the "Plugins/TrackStat" menu on the SqueezeBox/Transporter. You can also move from the standard browse menus to TrackStat statisitics by hitting the TS buttons in the web interface or holding play down for a while if a M is displayed in the upper right corner in a browse menu on the SqueezeBox/Transporter. When you goto the statistics by clicking the TS button or holding play the statistics will be shown in the context of the item you selected.
The following different ways of browsing the statistics are currently available:
|
Shows songs, album, artists with a specific rating. For albums and artists an average rating is calculated based on the ratings of all songs on the album/artists, unrated songs is calculated as a rating of 3. |
|
Shows the statistics information about albums, artists, genres, playlists, songs and years with a standard sorting. For example songs is sorted according to track number |
|
Shows the albums, artists or songs that hasn't been played for a long time. The sorting is done on the last played time statistic |
|
Shows the albums, artists or songs that was last added to SqueezeCenter Note that if TrackStat wasn't installed when you added the music to SqueezeCenter the last added time will be based on the last time the music file was modified. |
|
Shows the albums, artists or songs that was last played. This is basically a history log but it only show each album, artist, song once in the list. |
|
Shows the albums, artists or songs that has been played the least number of times. |
|
Shows the albums, artists or songs that has been played the least number of times, but it ignores those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums, artists or songs that has been played the least number of times, but it only include those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums, artists, genres, playlists, songs or years that has been played the most number of times. |
|
Shows the albums, artists or songs that has been played the most number of times, but it ignores those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums, artists or songs that has been played the most number of times, but it only includes those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums, artists or songs that has been played the most number of times, but it ignores those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums, artists or songs that has been played the most number of times, but it only includes those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums, artists or songs that has never been played |
|
Shows the albums or artists that has at least one song that hasn't been rated yet |
|
Shows the albums or artists that has at least one song that hasn't been rated yet, but it ignores those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums or artists that has at least one song that hasn't been rated yet, but only include those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums or artists that has at least one song that hasn't been rated yet, but it ignores those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums or artists that has at least one song that hasn't been rated yet, but only include those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. |
|
Shows the albums, artists or songs that hasn't been rated, but it ignores those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. When showing albums or artists only those that has no rated songs is shown. |
|
Shows the albums, artists or songs that hasn't been rated, but it only include those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. When showing albums or artists only those that has no rated songs is shown. |
|
Shows the albums, artists or songs that hasn't been rated, but it ignores those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. When showing albums or artists only those that has no rated songs is shown. |
|
Shows the albums, artists or songs that hasn't been rated, but it only include those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. When showing albums or artists only those that has no rated songs is shown. |
|
Shows the albums or artists that has at least one song which have never been played |
|
Show the albums, artists, genres, playlists, songs or years that has the highest ratings. For albums, artists, genres, playlists and years an average rating is calculated where unrated tracks is calculated as a rating of 3. |
|
Show the albums, artists or songs that has the highest ratings, but it ignores those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. For albums and artists an average rating is calculated where unrated tracks is calculated as a rating of 3. |
|
Show the albums, artists or songs that has the highest ratings, but it only includes those that has been added to SqueezeCenter within the last 30 days. The exact number of days is configurable in the TrackStat settings. For albums and artists an average rating is calculated where unrated tracks is calculated as a rating of 3. |
|
Show the albums, artists or songs that has the highest ratings, but it ignores those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. For albums and artists an average rating is calculated where unrated tracks is calculated as a rating of 3. |
|
Show the albums, artists or songs that has the highest ratings, but it only includes those that has been played within the last 30 days. The exact number of days is configurable in the TrackStat settings. For albums and artists an average rating is calculated where unrated tracks is calculated as a rating of 3. |
Playing music based on statistics
TrackStat provides a number of ways to start playing music based on the statistics
- You can browse the statistic in the web interface and hit the play icons, this will play all the songs for the item related to the play icon you clicked on. Note that if you clicked on a play icon beside an album when showing Not completely rated albums statistics this means that all tracks on the album will be played not just the unrated ones.
- You can browse the statistic with the remote on the SqueezeBox/Transporter and hit play, this will play all songs related to the item you clicked on.
- If you have installed the Dynamic Playlist plugin you can in the web interface click on the "Play as dynamic playlist" link. This will start playing a dynamic playlist based on the statistics you are currently showing. The dynamic playlist will continoue to play until all songs matching the selected statistic type has been played.
- If you have installed the Dynamic Playlist plugin you can on the SqueezeBox/Transporter browse with the remote to the "Music Library/Dynamic Playlists" menu and select the statistics playlist of your choice and hit play. This will start playing a dynamic playlist based on the statistics you are currently showing. The dynamic playlist will continoue to play until all songs matching the selected statistic type has been played.
- If you have installed the Dynamic Playlist plugin you can goto "Music Library/Dynamic Playlist" in the web interface, select the statistics playlist of your choice and hit play. This will start playing a dynamic playlist based on the statistics you are currently showing. The dynamic playlist will continoue to play until all songs matching the selected statistic type has been played.
Favorite statistics
By clicking on the "Select favorites" link in the TrackStat web interface you can select a number of statistics that you use often. The statistic types you selects will appear in the "Favorites" statistic group in the TrackStat web interface. The real use for this comes when you use TrackStat together with the Custom Browse plugin because then you can create a browse menu that makes it possible to browse statistics but it only shows the statistics you have selected as favorites.
SQL Playlist integration
TrackStat makes the following playlist types available in the SQL Playlist plugin. The advantage of using these playlists available through the SQL Playlist plugin is that you can have different settings for different playlist. With the dynamic playlists available through TrackStat the global TrackStat settings is used for all playlists.
|
Random playlist with only most played albums |
|
Random playlist with only most played artists |
|
Random playlist with only most played songs |
|
Random playlist with only not rated songs |
|
Random playlist with recently/not recently added albums |
|
Random playlist with recently/not recently added songs |
|
Random playlist with only top rated albums |
|
Random playlist with only top rated artists |
|
Random playlist with only top rated genres |
|
Random playlist with only top rated playlists |
|
Random playlist with only top rated songs |
|
Random playlist with only top rated years |
CLI interface
The prefered way to recieve event or getting information from TrackStat is to use the provided CLI interface. TrackStat provides the following CLI commands and events.
- Retreive rating for a track
- trackstat getrating 94
- trackstat getrating file:///mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3
- trackstat getrating /mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3
- 00:04:20:06:22:b3 trackstat getrating 94
- 00:04:20:06:22:b3 trackstat getrating file:///mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3
- 00:04:20:06:22:b3 trackstat getrating /mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3
- If the command succeeds it returns a "rating" parameter with the rating for the selected track between 0-5 and it also returns a "ratingpercentage" pamameter with the rating for the selected track between 0-100.
- Set rating for a track to 4 (or 85%)
- trackstat setrating 94 4
- trackstat setrating 94 85%
- trackstat setrating file:///mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 4
- trackstat setrating file:///mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 85%
- trackstat setrating /mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 4
- trackstat setrating /mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 85%
- 00:04:20:06:22:b3 trackstat setrating 94 4
- 00:04:20:06:22:b3 trackstat setrating 94 85%
- 00:04:20:06:22:b3 trackstat setrating file:///mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 4
- 00:04:20:06:22:b3 trackstat setrating file:///mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 85%
- 00:04:20:06:22:b3 trackstat setrating /mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 4
- 00:04:20:06:22:b3 trackstat setrating /mnt/mp3music_small/The%20Bodyguard/12%20Trust%20In%20Me.mp3 85%
- If the command succeeds it returns a "rating" parameter with the newly set rating between 0-5 and it also returns a "ratingpercentage" parameter with the rating for the selected track between 0-100.
- Event about changed rating for a track with trackid 94 and rating 4 (or rating percentage 85%)
- trackstat changedrating file%3A%2F%2F%2Fmp3music_small%2FThe%20Bodyguard%2F12%20Trust%20In%20Me.mp3 94 4 85%
- Event about changed statistics regarding playcount=18 and lastplayed=1144572357
- trackstat changedstatistic file%3A%2F%2F%2Fmp3music_small%2FThe%20Bodyguard%2F12%20Trust%20In%20Me.mp3 94 18 1144572357
Callback functions
The prefered way to receive events from TrackStat is using the CLI events, but there is also a number of callbacks which can be used. If a plugin implement any of these functions in its main plugin class they will be called by TrackStat when ratings or statistics are changed. The implementations below are just some small samples.
# This method will be called each time a rating value in TrackStat is changed by the user
# url = The url of the track on which the rating is changed
# rating = The new rating, a value between 0 - 100
sub setTrackStatRating {
my ($client, $url, $rating) = @_;
#
# Call your own methods and do some interesting stuff here
#
}
# This method will be called at the end of each played song
# url = The url of the track
#
sub setTrackStatStatistic {
my ($client,$url,$statistic)=@_;
my $playCount = $statistic->{'playCount'};
my $lastPlayed = $statistic->{'lastPlayed'};
my $musicbrainz_id = $statistic->{'mbId'};
my $rating = $statistic->{'rating'};
#
# Call your own methods and do some interesting stuff here
#
}
Database structure
Generally rating and statistic information is stored in:
- tracks_persistent - This is the table where Squeezebox Server/Logitech Media Server stores its rating information. When changing a rating in TrackStat it will always also write the information to this table, but note that the tracks_persistent table will generally be overwritten during rescans if your music files have RATING tags.
- track_statistics - This is the main TrackStat table, when changing a rating through TrackStat it's always stored in this table. This table also has some smart logic that avoids ratings to be overwritten during rescans when RATING tags are found. You can explicitly overwrite it by using the Custom Scan plugin scanning module Rating Tag. For the iTunes Statistics Import module which is provided by TrackStat and can be accessed through the Custom Scan plugin there are some smart logic that makes sure iTunes rating only overwrites ratings that are newer than the ones already existing in the track_statistics table.
- track_history - This is the history table for TrackStat data, whenever a rating is changed or a song is played it's written to this table. Based on the contents on this table it's possible to create the playback/rating history of a track which for example can be used to find out which tracks that have been played mostly during the last week.
track_statistics
The track_statistics table contains a single row for each song in your SqueezeCenter music library, the table consists of the following columns:
- url - The url of the track, the same value as in tracks.url
- urlmd5 - A MD5 checksum of the url, this column only exist in TrackStat 3.0 and later and it contains the same value as tracks.urlmd5
- musicbrainz_id - The musicbrainz id of the track if it has been tagged in the music file, the same value as in tracks.musicbrainz_id. This column is used to synchronize the url column after a rescan if files have been renamed or moved.
- playcount - The play count of the track
- added - The modification time of music file the first time it was part of a SqueezeCenter rescan. This value will not be updated if you have changed the file after the first rescan it was part of. Similar as the tracks.timestamp value, with the difference that tracks.timestamp is updated as soon as the modification time of the file is changed.
- lastplayed - The time when the track was played the last time. This is similar to the value in tracks.lastplayed with the difference that tracks.lastplayed is updated as soon as you play a millisecond of the track while the track_statistics.lastplayed is updated when you have played a part of the track. It is configurable how large amount of the track you need to play in the TrackStat section of "Server Settings/Plugins".
- rating - The rating of a track as a value between 1 and 100. Unrated tracks is represented as a null value.
When joining the information in track_statistics with the tracks table you should do this with:
tracks.url=track_statistics.url
Starting from TrackStat 3.0 and later it's also possible to join as this, which is a bit faster, but it's only needed in really large queries, so use the "url" joining unless usage of urlmd5 is needed.
tracks.urlmd5=track_statistics.urlmd5
track_history
The track_history table contains a single row for each time a song in your SqueezeCenter library has been played, so the table can contains the same track serveral times. The table consists of the following columns:
- url - The url of the track, the same value as in tracks.url
- urlmd5 - A MD5 checksum of the url, the same value as in tracks.urlmd5. This column only exists in TrackStat 3.0 and later.
- musicbrainz_id - The musicbrainz id of the track if it has been tagged in the music file, the same value as in tracks.musicbrainz_id. This column is used to synchronize the url column after a rescan if files have been renamed or moved.
- played - The time when the track was played.
- rating - The rating of the track at the time it was played.
When joining the information in track_history with the tracks table you should do this with:
tracks.url=track_history.url
When joining the information in track_history with the track_statistics table you should do this with:
track_statistics.url=track_history.url
For large queries where performance is critical, it's also possible to join as follows, but don't use this unless it's explicitly needed:
tracks.urlmd5=track_history.urlmd5
Or when joining the information in track_history with the track_statistics table you can in same way optionally use:
track_statistics.urlmd5=track_history.urlmd5
