diff --git a/docs/api/history.rst b/docs/api/history.rst deleted file mode 100644 index d749b940..00000000 --- a/docs/api/history.rst +++ /dev/null @@ -1,55 +0,0 @@ -History handling -================ - -For correct logical handling of ``previous()`` and ``previous_track`` backends -will need to keep track of which songs they have played. - -Normal playback ----------------- - -Each time a new song is played the previous ``current_track`` should be added to -the history. The ``previous_track`` should always be the most recent history item. - -Playback with repeat enabled ------------------------------ - -History should be handled in same manner as regular playback. ``next_track`` -at end of playlist should loop to first item on playlist. - -Playback with random enabled ------------------------------ - -Each song should only be played once until entire playlist has been played, -once this has occurred a new random order should be played. History should be -handled in the same way as regular playback. - -A suggested implementation is creating a shuffled copy of the tracks and -retrieving ``next_track`` from here until it is empty. - -Playback with consume enabled ------------------------------ - -Turning on consume should set history to an empty array, and not add any new -tracks while it is on. ``previous_track`` should return ``current_track`` to -match MPD behaviour. - -Playback with repeat and random -------------------------------- - -Once the shuffled tracks array is empty it should be replaced with a new -shuffled array of tracks. - -Playback with repeat and consume --------------------------------- - -Return ``current_track`` for ``previous_track`` to match MPD. - -Playback with random and consume --------------------------------- - -Return ``current_track`` for ``previous_track`` to match MPD. - -Playback with repeat, random and consume ----------------------------------------- - -Return ``current_track`` for ``previous_track`` to match MPD. diff --git a/mopidy/backends/__init__.py b/mopidy/backends/__init__.py index 962e91ba..8452f2a4 100644 --- a/mopidy/backends/__init__.py +++ b/mopidy/backends/__init__.py @@ -252,7 +252,14 @@ class BasePlaybackController(object): @property def next_track(self): - """The next :class:`mopidy.models.Track` in the playlist.""" + """ + The next :class:`mopidy.models.Track` in the playlist. + + For normal playback this is the next track in the playlist. If repeat + is enabled the next track can loop around the playlist. When random is + enabled this should be a random track, all tracks should be played once + before the list repeats. + """ if self.current_track is None: return None try: @@ -274,7 +281,12 @@ class BasePlaybackController(object): @property def previous_track(self): - """The previous :class:`mopidy.models.Track` in the playlist.""" + """ + The previous :class:`mopidy.models.Track` in the playlist. + + For normal playback this is the next track in the playlist. If random + and/or consume is enabled it should return the current track instead. + """ if self.current_track is None: return None try: