Skip to content

Developers

Jump to bottom
Mike Scheutzow edited this page Nov 6, 2015 · 9 revisions

This page is intended for developers interested in working on the code. Here is an overview of the structure of the Jukebox (and Juk) program source code. The app is written in C++, and makes extensive use of the Qt4 and KDE4 libraries.

##Program Class Structure

The top level is main(), which uses the KApplication and JuK classes.

###Graphical User Interface (GUI)

The JuK class which implements the main GUI window. It inherits from KXmlGuiWindow. JuK in turn uses the PlaylistSplitter and PlayerManager classes to do much of its work.

The PlaylistSplitter class implements most of the visible client area. It uses the PlaylistBox, SearchWidget, NowPlaying, Playlist, TagEditor and LyricsWidget classes to create different regions of the client area.

The row of player buttons and track progress bar just under the menu bar are handled by the PlayerManager class. The volume button on the right is implemented by the VolumePopupButton class. The track position slider is handled by the TimeSlider and TrackPositionAction classes.

The tall panel on the left with one icon per playlist (in default view) is implemented by the PlaylistBox class.

The (sometimes not visible) panel which provides the search field is implemented by SearchWidget.

The (sometimes not visible) panel which shows the currently-playing track title, artist and album cover is implemented by the NowPlaying class.

The table of track information in the center is implemented by the Playlist class. It has one audio file per table row. The row is implemented by the PlaylistItem class, which holds the track metadata.

The (sometimes not visible) panel which shows the lyrics for the current track is implemented by LyricsWidget class.

The (sometimes not visibile) panel which provides Tag Editing is implemented by the TagEditor class.

###Playlist Classes There are several specialized types of Playlist classes used by this app. The following classes extend Playlist, which acts as a base class:

  • CollectionList - a list of all the songs in a set of user-specified directory trees. This is the default music library.
  • DynamicPlaylist - a temporary union of one or more Playlist objects. Used by SearchPlaylist, or if multiple selections are made in the PlaylistBox..
  • FolderPlaylist - consists of all songs present in a user-specified directory.
  • HistoryPlaylist - a list of the songs recently played.
  • SearchPlaylist - all songs from CollectionList which match a user-specified search query; it is recalculated when CollectionList changes.
  • UpcomingPlaylist - a temporary list assembled by the user. It's icon is Labeled "Play Queue" in the GUI.
  • TreeViewItemPlaylist - an auto-created SearchPlaylist used to group existing tracks by Artist, Album and Genre. Used for the PlaylistBox Tree Mode.
  • this Jukebox fork added NormalPlaylist to represent an m3u playlist, and changed Playlist into an abstract class.

##Other classes

  • PlayerManager is the class which actually plays audio. It uses the KDE Phonon library to do almost all of the work (read file, decompress, buffer, send samples to audio device.) This class issues Signals when interesting things happen, so that other parts of the application can update themselves. This class knows nothing about play lists; instead, it uses the PlaylistInterface API to ask what the next song to play should be. The PlaylistInterface is implemented by PlaylistCollection.
  • PlaylistCollection is a chaotic set of utility methods for working with all the types of Playlist. This class is easily confused with CollectionList; it really should have a better name. This is a singleton class. This class implements the PlaylistInterface needed by PlayerManager.
  • TrackSequenceManager is a singleton class used to remember the currently-playing song, and to choose the next song to be played. The strategy used to pick the next song is implemented by a class which implements the TrackSequenceIterator interface.
  • DefaultSequenceIterator implements multiple methods for choosing the next song. The simplest method is 'next song in same playlist'. Other methods are 'choose randomly from the whole collection', or 'next song in current search list'. This class is odd, because normally those using this object-oriented pattern implement a single method per class, which tends to give much cleaner code.
  • UpcomingSequenceIterator is a different implementation of TrackSequenceIterator, used only with UpcomingPlaylist class. It has the additional unusual behavior of auto-deleting the track from UpcomingPlaylist after it plays.

##Application Caches Juk uses two files to store playlist information between program runs. There is the Playlist Cache and the Collection List Cache. The backing files are created in $HOME/.kde/share/apps/jukebox/. The caches serve two purposes: to make the app start up faster, and to store the content of a playlist that has no .m3u file on disk.

###Playlists Cache This stores only the playlist name and the track filenames (or pattern.) The file on disk is named 'playlists'. This cache has one record for each playlist in the left panel, except for 'Collection List' which is handled as a special case. The fields in a record depend on the type of playlist:

The data fields for a Normal Playlist record are:

  • playlist name
  • absolute filename (*.m3u)
  • list of abs. track file names (*.mp3, etc.)
  • sort column id

The data fields for a Search Playlist record are:

  • playlist name
  • search pattern
  • sort column id

The data fields for a Folder Playlist record are:

  • playlist name
  • folder path
  • sort column id

The data fields for a Upcoming Playlist record are:

  • abs. track filename
  • sort column id

The data fields for a History Playlist record are:

  • abs. track filename
  • timestamp when last played
  • sort column id

###Collection List Cache The 'cache' cache hold data from CollectionList, and has one record for each track stored in this playlist. The file on disk is 'cache'. The fields are:

  • abs. file name (*.mp3, etc.)
  • title
  • artist
  • album
  • track num
  • year
  • comment
  • bitrate
  • track duration (formatted mm:ss)
  • track duration (as integer seconds)
  • file's last modified timestamp

Home

Clone this wiki locally