-
Notifications
You must be signed in to change notification settings - Fork 3
/
README
303 lines (189 loc) · 7.96 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
test
GNUMP3d - The GNU Streaming MP3 / OGG Vorbis Server.
Homepage: http://www.gnump3d.org/
Version : 3.0
Author : Steve Kemp <[email protected]>
NOTE
----
All development of this branch of the project has ceased.
In the future there might be a GNUMP3d 3.x branch writen in
modern Perl, or Ruby, supporting an SQLite back-end. However
there are no plans to start on this in the short-term future.
Contents
--------
This README file is split into the following sections.
Please read it all before reporting bugs, or problems:
Introduction
Supported Platforms
Installing
Configuration
Running
Customisation
Documentation
Mailing Lists
Reporting Bugs
License (GPL)
Alternative Solutions
Thanks
Comments / Suggestions / Patches?
Recent Changes
Introduction
------------
This server attempts to provide an attractive interface to browsing
and streaming a large MP3 or OGG collection via your web browser.
It allows MP3's and OGG Vorbis files to be served to any media player
which supports audio streaming. Supported players include XMMS, FreeAmp
and WinAmp.
In addition to this support is also present for streaming MPEG video
files direct to clients.
--
NOTE: The streaming of movies requires a player capable of supporting
HTTP downloads.
-
The streaming is very versatile; individual files may be played directly,
whole directory trees can be streamed, you may even choose to listen to
audio files which match a particular pattern.
The display of files is built up in real-time; which means that
you don't need to restart the server when adding music to your
collection. Although as an optimization song tag details are only refreshed
when a supplied indexing script runs.
Supported Platforms
-------------------
This software was primarily developed under Debian GNU/Linux, and
should run on any similar GNU/Linux development platform.
Because the software is written with the portable scripting
language, Perl, it should also run under other flavours of Unix.
GNUMP3d has been tested upon the following platforms:
GNU/Linux FreeBSD OpenBSD
NetBSD Solaris
Microsoft Windows(*)
--
(*) Using the most current version of the ActiveState Perl distribution only.
Installing under Unix
---------------------
From the unpacked archive simply run 'make install'.
The software can also be purged by running 'make uninstall' - if you have
the original unpackaged archive.
After installing the software you may well want to run the test scripts,
you can do this by simply running 'make test'. Any failures at this
point are bugs - and should certainly be reported as such.
Configuration
-------------
When the server starts it looks for the global configuration file,
which defaults to /etc/gnump3d/gnump3d.conf - you may instead copy
this file to your home directory, as '.gnump3drc' in which case
the personal configuration file will override the system wide one.
You may supply the location of an alternative configuration file
via the '--config' command line option.
NOTE:
You will definitely need to edit the config file prior to running
the server for the first time.
Running
-------
The first time you start the server you should make sure you
have a current "index" of your music. To generate an index
please run the script 'gnump3d-index' after updating your
configuration file as discussed above.
Once you have an index you should run the main script, 'gnump3d'
to start the streaming server.
Once the server is started point a web browser at the host and
port which you have specified, and browse/stream away.
After you have verified that the server works you may wish to
run it in the background. To do this create a startup script
for your platform and mail it to me - if there isn't one included
in 'rcfiles/'
Customisation
-------------
The appearance of the server may be changed by switching to a new
theme. The themes may be browsed and selected from the HTML pages
which are generated - if you wish to change the default theme please
see the configuration variable 'theme' in gnump3d.conf for details.
You may freely modify the theme files themselves, or create a new
theme to change the appearance of the server.
(Theme files are stored in a directory with the name of the theme in
the /usr/share/gnump3d/ directory).
Documentation
-------------
The documentation included with this software includes several
'man pages' which are installed along with the software, those
along with this document, and the project's website should contain
all the information you need to run the software.
The man pages should be installed when you install the software,
if you need help on something try the following commands:
man gnump3d
man gnump3d.conf
man gnump3d-top
Mailing Lists
-------------
There are two mailing lists which you can turn to if you'd like
help, assistance, or discussion on this software.
Full details of these are given on the project's website, at
the following URL:
http://www.gnump3d.org/lists.html
NOTE: You must be subscribed to the mailing lists in order to
post messages. This is a regretable position made necessary by
the amount of spam an open mailing list would receive.
Reporting Bugs
--------------
For a bug report to be useful it needs to contain as
much information as possible.
A simple means of giving all the relevant information is
to use the integrated bug reporting plugin. (Obviously you
can't use this if the bug you wish to report concerns
plugins ;).
To use the bug reporting plugin simply point your web browser
at:
http://server:port/bug/
Enter the text of your report into the text area, and click
on the submit button.
If you're not using the bug reporting plugin simply send
me an email. To assure prompt attention please include the
following information:
1. Your operating system, and version:
Run 'uname -a', and 'arch' and send me the results.
2. The version of GNUMP3d you're using.
Run 'gnump3d --version' and send me the results.
2a. The output of 'gnump3d --dump-plugins' if you're having
problems with the plugin support.
3. The browser/client/MP3 player you're using.
If you can send a patch that would be great; if not the more
detailed your report is the better.
License
-------
As the name might suggest, this software is distributed under
the terms of the GNU Public License, version 2.
Please find a copy of the GNU Public License included with the
source archive in the file COPYING, it will also be accessible
from the server itself; read the startup banner for details.
Alternative Solutions
---------------------
Here's a brief list of alternative solutions which
you may want to investigate if this software doesn't
quite meet your needs.
Edna - http://edna.sourceforge.net/
This is very similar to this application, in fact this server
was initially modelled after Edna.
Edna lacks searching facilities, tag display for OGG files, and
is written in Python.
Ample - http://ample.sourceforge.net/
This is a simple server which is comparable to Shoutcast.
KPlaylist - http://www.kplaylist.net/
This is a PHP-based solution which allows you to add individual
files to your playlist via your web browser then play it.
KPlaylist requires a database backend.
Thanks
------
I'm indebted towards many people who sent me bugfixes, corrections,
interesting questions and suggestions.
It is with their help that this software is what it is today, and I
can't thank them highly enough. Any remaining bugs are of course
entirely my fault.
Comments / Suggestions / Patches?
---------------------------------
I optimistically welcome comments, feedback, suggestions, updated
documentation and contributed themes/logos.
If you really like the software consider purchasing something from
the wishlist you'll find displayed at http://www.gnump3d.org/
Steve
---