1mps
2===
3
4.. image:: http://badge.fury.io/py/mps.png
5 :target: https://pypi.python.org/pypi/mps
6.. image:: https://pypip.in/d/mps/badge.png
7 :target: https://pypi.python.org/pypi/mps
8.. image:: https://pypip.in/wheel/mps/badge.png
9 :target: http://pythonwheels.com/
10 :alt: Wheel Status
11
12
13Features
14--------
15- Search and stream music
16- Search albums or single tracks
17- Create playlists
18- Download tracks
19- Works with Python 2.7+ and 3.3+
20- Works with Windows, Linux and Mac OS X
21- No Python dependencies
22- Requires mplayer
23
24Screenshots
25-----------
26
27Search
28~~~~~~
29
30.. image:: http://i.imgur.com/SnqxqZz.png
31
32Playback
33~~~~~~~~
34
35.. image:: http://i.imgur.com/3sYlktI.png
36
37Playlists
38~~~~~~~~~
39
40.. image:: http://i.imgur.com/RDEXLPW.png
41
42
43
44Installation
45------------
46
47Using `pip <http://www.pip-installer.org>`_::
48
49 [sudo] pip install mps
50
51Using `git <http://www.git-scm.com>`_::
52
53 git clone https://github.com/np1/mps.git
54 cd mps
55 python setup.py install
56
57Manually:
58
59 Download `zip <https://github.com/np1/mps/archive/master.zip>`_ or `tar.gz <https://github.com/np1/mps/archive/master.tar.gz>`_ and extract
60
61 From within the mps directory::
62
63 python setup.py install
64
65
66Mac OS X installation notes
67~~~~~~~~~~~~~~~~~~~~~~~~~~~
68
69Install mplayer with `MacPorts <http://www.macports.org>`_::
70
71 sudo port install MPlayer
72
73
74Windows installation notes
75~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
77Install the python `colorama <https://pypi.python.org/pypi/colorama>`_ module to get colors (optional)::
78
79 pip install colorama
80
81Download mplayer for your CPU type from the "Build Selection table" `here
82<http://oss.netfarm.it/mplayer-win32.php>`_.
83
84Extract the mplayer.exe file, saving it to your mps directory or a PATH
85directory
86
87
88Upgrading
89---------
90
91It is recommended you update to the latest version.
92
93Upgrade pip installation::
94
95 sudo pip install mps --upgrade
96
97Upgrade git clone::
98
99 (from within the mps directory)
100
101 git pull
102
103Usage
104-----
105
106mps is run on the command line using the command::
107
108 mps
109
110Enter ``h`` from within the program for help.
111
112Searching
113~~~~~~~~~
114
115You can enter an artist/song name to search for songs.
116Track searches must be prefixed with either a . or / character.
117
118Enter ``n`` or ``p`` to go to the next / previous page of results
119
120To search for an album, enter ``album`` optionally followed by the album title.
121
122When a list of songs is displayed, such as search results or a playlist, you
123can use the following commands:
124
125Downloading
126~~~~~~~~~~~
127``d 3`` to download song 3
128
129Playback
130~~~~~~~~
131
132``all`` to play all displayed tracks
133
134``1,2,3`` to play songs 1 2 and 3
135
136``2-4,6,6-3`` to play songs 2, 3, 4, 6, 6, 5, 4, 3
137
138Note: The commands ``shuffle`` and ``repeat`` can be inserted at the start or
139end of any of the above to enable those play modes: eg, ``shuffle 1-4`` or
140``2-4,1 repeat``
141
142Editing
143~~~~~~~
144``rm 1,5`` to remove songs 1 and 5.
145
146``rm 1,2,5-7`` to remove songs 1,2 and 5-7.
147
148``rm all`` to remove all songs
149
150``sw 1,3`` to swap the position of songs 1 and 3
151
152``mv 1,3`` to move song 1 to postion 3
153
154Playlist commands
155~~~~~~~~~~~~~~~~~
156
157``add 1,2,3`` to add songs 1,2 and 3 to the current playlist.
158
159``add 1-4,6,8-10`` to add songs 1-4, 6, and 8-10 to the current playlist
160
161``add 1-4,7 <playlist_name>`` to add songs 1-4 and 7 to a saved playlist. A
162new playlist will be created if the given name doesn't already exist.
163
164``vp`` to view the current playlist (then use rm, mv and sw to modify it)
165
166``ls`` to list your saved playlists
167
168``open <playlist_name or ID>`` to open a saved playlist as the current playlist
169
170``view <playlist_name or ID>`` to view a playlist (leaves current playlist intact)
171
172``play <playlist_name or ID>`` to play a saved playlist directly.
173
174``save`` or ``save <playlist_name>`` to save the currently displayed songs as a
175stored playlist on disk
176
177``rmp <playlist_name or ID>`` to delete a playlist from disk
178
179``mv <old_name or ID> <new_name>`` to rename a playlist
180
181``q`` to quit
182
183``h`` for help
184
185Other Commands
186--------------
187
188``top`` show top tracks this week
189
190``top3m`` show top tracks for last 3 months
191
192``top6m`` show top tracks for last 6 months
193
194``topyear`` show top tracks for last year
195
196``topall`` show all time top tracks
197
198``list [pleer playlist url]``` to import a playlist from the web.
199
200Advanced Tips
201-------------
202
203Playlist Name Completion
204~~~~~~~~~~~~~~~~~~~~~~~~
205
206When using ``open``, ``view`` or ``play`` to access a playlist, you can enter
207the first few characters instead of the whole name. The first alphabetically
208matching playlist will be opened / displayed.
209
210Invocation
211~~~~~~~~~~
212
213To play a saved playlist when invoking mps use the following command:
214
215 ``mps play <playlistname>``
216
217This also works for other commands, eg:
218
219 ``mps .mozart`` to search
220
221 ``mps view <playlistname>`` to view a saved playlist
222
223 ``mps ls`` to list saved playlists
224
225 ``mps top`` to list top tracks this week
226
227 ``mps open moz`` to open a saved playlist called mozart.
228
229Specifying Ranges
230~~~~~~~~~~~~~~~~~
231
232When selecting songs for playback, removing or adding you can use ``5-`` to
233select song 5 upward and ``-5`` to select up to song 5. This can be included
234with other choices so for example: ``5,3,7-,-2``. You can also use spaces
235instead of commas eg. ``5 3 7- -2``.
236
237Quality / Bitrate
238~~~~~~~~~~~~~~~~~
239
240Add ``+best`` to a search query to return high bitrate results or ``+good`` to
241exclude them.
242
243Using MPV instead of MPlayer
244~~~~~~~~~~~~~~~~~~~~~~~~~~~~
245
246If you have `mpv <http://mpv.io>`_ installed and want to use that instead of mplayer;
247
248From within mps::
249
250 set player mpv
251 set playerargs --really-quiet --no-video
252
253Other Configuration
254~~~~~~~~~~~~~~~~~~~
255
256To view configuration, enter ``set`` and to change any item enter:
257``set <item> <value>``. This can be used to change the download path (DDIR)
258and will persist after exiting the program. To reset all settings to default,
259use ``set all default`` or for a single item, ``set <item> default``
260
261Disclaimer
262~~~~~~~~~~
263
264Use this software at your own risk, it downloads content from pleer.com, an
265online mp3 file repository.
266