|
Welcome to phpJuke version A: The sensible streaming media manager in PHP. »
Readme
I. phpJuke Readme Introduction: phpJuke is a simple PHP application for streaming media management. Rather than plain playlist management, phpJuke will let you have separate playlists for each unique style in your music website/radio, and users will choose what styles (and to what degree) they like best. A final playlist (that defaults to a Real Media® .SMIL file) will be generated at random and delivered to the user. Let's imagine 3 styles: Pop, Rock and Hip-Hop. You build an unique playlist for each one, then visitor A may decide he wants to listen to Hip-Hop only, but visitor B may want a little of each style, but with more emphasis on Rock. Your visitors control what percentage of each style's available songs they want to hear, but then the playlist is created at random - with the exception that all Rock songs on the generated playlist will play first, then all Pop songs and so on - this prevents heavy 'breaks' on your 'radio show' - it may look like a nice idea to let everything run randomly at first, but trust me - it's not. Another nice feature is that phpJuke uses cookies so that a visitor's settings are remembered once he comes back, without any password hassle. As you can see, this is all pretty unique and specialized, and this is why I have created phpJuke - because I couldn't find such a script on the Web. I am not an experienced programmer - in fact this is my first serious attempt at something like this. So if you think you could do better, have your try. As I am a strong believer in the open-source movement, the good news is that phpJuke is totally free for everyone's use, even for big-arse corporations. The bad news is that I am such an inexperienced programmer that there should be quite a few bugs. I've created phpJuke for use on my own Bleep Radio (which is running fine), so it's unlikely upgrades will be available often. Anyway, there should be enough features for the average webmaster, and experienced PHP programmers may find an interesting start for more advanced applications.
License: I, Eduardo J. Sousa, cannot be held responsible for any harm caused by phpJuke. You may use phpJuke at your own risk. You may freely use and distribute phpJuke as long as you keep the distribution intact (i.e. include this readme file, etc). Or, you can also make any changes you desire to phpJuke as long as this original script and its creator - Eduardo Sousa - are credited.
II. phpJuke Install & Administration Guide Requirements: phpJuke has been tested on an Apache webserver running on BSD/OS, and also on the Xitami webserver on typical Windows98. Both configurations were running PHP4, and it's unknown whether phpJuke will run on PHP3. No database is required as phpJuke uses plain text files. You also need a machine/server or hosting account with streaming media capabilities, such as a Real Server®. Depending on your media format of choice, typical HTTP streaming may also be supported, but not recommended.
Unpacking and setting up permissions: You should unpack the phpjuke-a.zip file and set up the following permissions:
Editing the files: The red files in the previous list should be edited before uploaded. Here's how: /config.txt: this one is commented, and quite easy to fill. But please be careful! /data/styles.txt: the core styles file, perhaps the most important configuration file. It is a plain text file containing the description for each style. It works like this:
A possible styles.txt would be:
Don't forget, the each playlist file must be present in the same directory as styles.txt. In case you are wondering what is the style description for, it is used on an IE (and NS6) <td title="..."> tag. Also, please be very careful, don't leave any blank lines after the last '||'. /data/<playlist>.txt: playlist files, as described on styles.txt. Playlists go like:
A possible file would be:
Media files are placed in the final .smil playlist. As people normally use a 'base' tag for these (as used in tpl_playlist.txt), I've used relative paths in the example, otherwise you might need to write down absolute rtsp://... (or http://...) URLs. Again, please be very careful, don't leave any blank lines after the last '||'. /data/tpl_playlist.txt:
The SMIL playlist template. It defaults to Real Networks' language,
but with some editing you can make a Windows Media template. Don't remove
the $realplaylist variable though, that's where the generated playlist
will go. Unless you want something more complicated, you only need to
change the meta tags, including the all important
Uploading and testing: After you
have made these changes, you can upload the files and set permissions
as specified before. You'll also need the corresponding media files, of
course, so after you upload everything, set your browser to
Optional editing /phpjuke.php: The ubiquous PHP file that makes it work, the jukebox file is a plain HTML file with the following differences:
The previous
code, placed above the opening
Will place a table containing the first N items (as defined in config.txt) in the users' playlist. It'll also place a link that starts streaming the playlist.
This one places the table with the preferences selector, that lets the users select the styles and respective amounts they want to hear. /playlist.php:
Like phpjuke.php, contains the same code before the opening
/data/tpl_meta.txt: The template that generates a metafile (normally .ram), pointing to the playlist file, as required by Real Audio® streams. It shouldn't be edited, but possibly other systems (such as Windows Media) require a different metafile.
/data/tpl_meta2.txt: As above, the template that generates a second metafile (such as .rpm files) that might have some use for some of you hacking phpJuke ;) . Normally not used and disabled in config.txt. /data/tpl_plitem.txt: Another template, this one defines the basic structure of each item placed on the SMIL playlist (defined by tpl_playlist.txt - placed in $realplaylist). Don't change this if you are using SMIL/Real, else use these vars:
/include/playlist.inc:
The PHP script that will generate the table containing the
complete playlist. You might edit some parts but be very careful. Don't
forget to escape when placing HTML double commas by using /include/pl-genstyles.inc: As above, the PHP script that places a table containing the preferences selector. Be very careful when editing! /include/pl-short.inc: The short playlist display. Be careful!
III. Final Words I hope that this script works for you and, more important, that you find this useful and that you spread this to others. I'd really like to see someone taking phpJuke and transforming it into a decent and really powerful script, but at the moment I am leaving phpJuke version A (don't people get tired of numbers?) and back to what I do and like best - design and computer graphics. Feel free to come visit my main internet resource at www.asseptic.org. Sooner than expected, who knows?, maybe I'll come up with phpJuke B. Cheers, Eduardo Sousa (edsousa@asseptic.org)
IV. Troubleshooting If you keep getting Error 500 or the .ram file doesn't load You might try deleting the .htaccess file in the /users/ directory. The .htaccess file is intended to keep Real Player from caching an old .smil (rendering new playlists useless for a certain number of users). However, in some cases this might provoke errors, so you'll need to delete that .htaccess file. You might even run away with it. Anyway, I'm studying a better method of controlling caches.
|
|
| phpJuke A - 15.Sep.2001, by Eduardo Sousa - homepage: www.asseptic.org/lab/phpjuke |