1 # -*- coding: utf-8 -*-
6 This module provides enough functionality to create a frontend to control
7 Panucci as well as exporting a large portion of the Panucci API over D-Bus.
10 from __future__
import absolute_import
15 from panucci
import player
16 from panucci
import services
19 class PanucciAPI(services
.ForwardingObservableService
, dbus
.service
.Object
):
21 Panucci's public API for use in frontend development.
27 Emitted when the file starts playing.
29 Emitted when the file is paused.
31 Emitted when the file is stopped.
33 Emitted when the player reaches the end of the file.
34 "end-of-playlist" : ()
35 Emitted when the player reaches the end of the playlist.
36 "new-track-loaded" : ()
37 Emitted when the player changes track.
38 "new-metadata-available" : ()
39 Emitted when new metadata for the current track is available. Use
40 the get_metadata function to retrieve it.
41 "playlist-to-be-overwritten" : ()
42 Emitted when a playlist is about to be over-written. If the function
43 returns True the playlist will be over-written. Otherwise the
44 over-write will be aborted.
45 "item-added" : ( item-id )
46 Emitted when an item is added to the playlist.
47 "item-removed" : ( item-id )
48 "item-moved" : ( item-id, from-pos, to-pos )
49 "bookmark-added" : ( bookmark-id )
50 "bookmark-removed" : ( bookmark-id )
54 "new-metadata-available" : "new-metadata-available",
55 "playlist-to-be-overwritten": "playlist-to-be-overwritten",
56 "end-of-playlist" : "end-of-playlist",
57 "item-removed" : "item-removed",
58 "item-moved" : "item-moved",
59 "bookmark-added" : "bookmark-added",
60 "new-track-loaded" : "new-track-loaded",
61 "bookmark-removed" : "bookmark-removed",
62 "item-added" : "item-added", }
64 playlist_signals
= { "playing" : "playing",
66 "end-of-file" : "eof",
67 "stopped" : "stopped", }
69 signals
= player_signals
.keys() + playlist_signals
.keys()
72 self
.__log
= logging
.getLogger("panucci.api.PanucciAPI")
73 services
.ForwardingObservableService
.__init
__( self
,
76 self
.__player
= player
.player
77 self
.__playlist
= self
.__player
.playlist
79 self
.forward( self
.__player
, self
.player_signals
)
80 self
.forward( self
.__playlist
, self
.playlist_signals
)
83 """ Can be called by the frontend when it's initialized. This loads
84 the last played track then sends the appropriate signals to
85 populate the frontend's UI (namely: new-track-loaded and
86 new-metadata-available) """
91 """ Should be called when the user exits the application. This stops
92 the player and creates a resume bookmark. """
98 """ Starts playing the current track in the playlist. Does nothing if
99 the playlist is empty or if the player is already playing. """
101 return self
.__player
.play()
104 """ Pauses the current track. Does nothing if the playlist is empty or
105 the track is paused or stopped. """
107 return self
.__player
.pause()
109 def play_pause_toggle(self
):
110 """ Calls play() if the player is paused, calls pause() if the player
111 is playing, does nothing if the player is stopped."""
113 return self
.__player
.play_pause_toggle()
116 """ Stop the currently playing (or paused) track. """
118 return self
.__player
.stop()
120 def next_track(self
, loop
=False):
121 """ Changes to the next track in the playlist. If "loop" is set to
122 True, then when the end of the playlist is reached it will loop
123 to the beginning and continue playing. """
125 return self
.__playlist
.skip( skip_by
=1, loop
=loop
)
127 def previous_track(self
, loop
=False):
128 """ Changes to the previous track in the playlist. If "loop" is set to
129 True and the current track is the first in the playlist then this
130 function will skip to the last track in the playlist. """
132 return self
.__playlist
.skip( skip_by
=-1, loop
=loop
)
134 def seek(self
, from_beginning
=None, from_current
=None, percent
=None ):
135 """ A very flexible function to seek in the current file
137 Params: Requires ONE of the following keyword arguments
138 - from_beginning=n: seek n nanoseconds from the start of
140 - from_current=n: seek n nanoseconds from the current
142 - percent=n: seek n percent from the beginning of the file
144 Returns: False if the seek was NOT possible
145 ( position, duration ) if the seek was possible
148 return self
.__player
.do_seek( from_beginning
= from_beginning
,
149 from_current
= from_current
,
152 def get_position_duration(self
):
153 """ Returns the position in the current file and the duration in
154 nanoseconds (10**-9). Returns ( -1, -1 ) if seeking is not possible
155 or if no file is loaded. """
157 return self
.__player
.get_position_duration()
159 def get_metadata(self
):
160 """ Returns a dict containing metadata related to the current file
161 being played. It can contain the following keys:
162 "title" - The title of the track
163 "artist" - The artist tag for the track
164 "album" - The album tag for the track
165 "coverart" - A binary blob representing an image
166 "length" - The length in nanoseconds of the track
169 return self
.__playlist
.get_file_metadata()
172 def play_uri(self
, uri
):
173 """ Erase the playlist and start playing URI. The only supported URI
174 at the moment is file:// followed by an absolute path.
175 If the playlist has been modified since it was loaded a
176 "playlist-to-be-overwritten" signal will be emitted. """
178 return self
.__playlist
.load(uri
)
180 def play_directory(self
, dirpath
):
181 """ Same as play_uri except dirpath is just an absolute path to a local
182 directory. All the files in the directory will be loaded. """
184 return self
.__playlist
.load_directory(dirpath
)
186 def queue_uri(self
, uri
):
187 """ Adds a URI to the end of the playlist, see play_file for supported
188 URIs. If the playlist is empty the file will start playing. """
190 return self
.__playlist
.append(uri
)
192 def queue_directory(self
, dirpath
):
193 """ Same as queue_uri except dirpath is just an absolute path to a local
194 directory. All the files in the directory will be queued. """
196 return self
.__playlist
.load_directory( dirpath
, append
=True )
199 def add_bookmark_at_current_position( self
, name
=None ):
200 """ Adds a bookmark at the current position in the track. The
201 bookmark's name will be a formatted version of the position
202 (hh:mm:ss). If a name is provided it will be used instead. """
204 return self
.__player
.add_bookmark_at_current_position( label
=name
)
207 def get_playlist_item_data( self
, item_id
):
210 def remove_bookmark(self
, bookmark_id
):
214 def get_recent_files(self
):
218 def show_main_window(self
):