sima/lib/player.py

   1 # -*- coding: utf-8 -*-
   2 # Copyright (c) 2009-2014 Jack Kaliko <jack@azylum.org>
   3 #
   4 #  This file is part of sima
   5 #
   6 #  sima is free software: you can redistribute it and/or modify
   7 #  it under the terms of the GNU General Public License as published by
   8 #  the Free Software Foundation, either version 3 of the License, or
   9 #  (at your option) any later version.
  10 #
  11 #  sima is distributed in the hope that it will be useful,
  12 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 #  GNU General Public License for more details.
  15 #
  16 #  You should have received a copy of the GNU General Public License
  17 #  along with sima.  If not, see <http://www.gnu.org/licenses/>.
  18 #
  19 #
  20
  21 # TODO:
  22 # Add decorator to filter through history?
  23
  24 # standard library import
  25 import logging
  26
  27 # local import
  28 #from sima.lib.track import Track
  29
  30
  31 class Player(object):
  32     """Player interface to inherit from.
  33
  34     When querying player music library for tracks, Player instance *must* return
  35     Track objects (usually a list of them)
  36
  37     Player instance should expose the following immutable attributes:
  38         * artists
  39         * state
  40         * current
  41         * queue
  42         * playlist
  43         *
  44     """
  45
  46     def __init__(self):
  47         super().__init__()
  48         self.log = logging.getLogger('sima')
  49
  50     def monitor(self):
  51         """Monitor player for change
  52         Returns :
  53             * database  player media library has changed
  54             * playlist  playlist modified
  55             * options   player options changed: repeat mode, etc…
  56             * player    player state changed: paused, stopped, skip track…
  57         """
  58         raise NotImplementedError
  59
  60     def clean(self):
  61         """Any cleanup necessary"""
  62         pass
  63
  64     def remove(self, position=0):
  65         """Removes the oldest element of the playlist (index 0)
  66         """
  67         raise NotImplementedError
  68
  69     def find_track(self, artist, title=None):
  70         """
  71         Find tracks for a specific artist or filtering with a track title
  72             >>> player.find_track('The Beatles')
  73             >>> player.find_track('Nirvana', title='Smells Like Teen Spirit')
  74
  75         Returns a list of Track objects
  76         """
  77         raise NotImplementedError
  78
  79     def find_album(self, artist, album):
  80         """
  81         Find tracks by track's album name
  82             >>> player.find_album('Nirvana', 'Nevermind')
  83
  84         Returns a list of Track objects
  85         """
  86         raise NotImplementedError
  87
  88     def find_albums(self, artist):
  89         """
  90         Find albums by artist's name
  91             >>> player.find_alums('Nirvana')
  92
  93         Returns a list of string objects
  94         """
  95         raise NotImplementedError
  96
  97     def fuzzy_find_artist(self, artist):
  98         """
  99         Find artists based on a fuzzy search in the media library
 100             >>> bea = player.fuzzy_find_artist('beatles')
 101             >>> print(bea)
 102             >>> ['The Beatles']
 103
 104         Returns a list of strings (artist names)
 105         """
 106         raise NotImplementedError
 107
 108     def disconnect(self):
 109         """Closing client connection with the Player
 110         """
 111         raise NotImplementedError
 112
 113     def connect(self):
 114         """Connect client to the Player
 115         """
 116         raise NotImplementedError
 117
 118 # VIM MODLINE
 119 # vim: ai ts=4 sw=4 sts=4 expandtab