rbDJ -- by Garrett Albright -- albright (a) anre (full stop) net v0.9.6 -- 13 Mar 2005 http://www.anre.org/rbdj UPGRADING --------- If you are upgrading from a previous version of rbDJ, please read "UPGRADING.text" for special instructions. ABOUT ----- rbDJ is a PHP script designed to work with astro's radio.blog, a widget you can embed into web pages to allow visitors to listen to music as they browse your site. rbDJ allows members of a community to upload their own music in MP3 format into radio.blog's playlist, turning it into into a sort of community radio station. rbDJ can be integrated into forums, blogs and CMSs which feature a member database. Administrators will also have administrator privileges on rbDJ. radio.blog can be found here: http://www.radioblogclub.com/ Integration-wise, at present, rbDJ *only* integrates with phpBB forums configured to use MySQL. However, rbDJ has a "Generic" setting which allows it to run independently of a database, so even if your community's software is not directly supported with rbDJ, your community can still use it. If you are familiar with PHP, please consider writing and contributing a "port" of rbDJ to other community scripts. See the bottom of rbdj.php for the relevant code. rbDJ has only been tested with radio.blog versions 2.0 through 2.2. Also, rbDJ has only been tested on Unix/Linux. Compatibility with Windows-based servers is unknown... If you're using a Windows server, please contact me to let me know if this works or not. HOW rbDJ WORKS -------------- The person installing rbDJ sets several settings upon installation; what forum/CMS/etc and database rbDJ will work with (if any), how many posts and days registered members must have under their belt before they can use rbDJ, how many song "slots" there will be, and how old a song must be before its slot opens up. When a user uploads a song, it fills up a slot; when all slots are filled, users can no longer upload songs. However, once a song has been in the playlist for a certain number of hours, its slot will "open" and users will be able to upload a song again. That song will take the place of the song in the "open" slot; the old song will be "purged." Users can listen to the song they just uploaded (or any other song) by clicking on the musical note next to the song's name; that will cause radio.blog to open up and play only that song. If radio.blog's finicky music player doesn't like it, they can then delete the song. Administrators can break most of the rules that normal users must follow. They can delete other users' songs and "lock" a song so that its slot will never be purged. CAVEATS ------- Due to a glitch -- er, "feature" -- in PHP, song files which have an apostrophe in the filename will be "clipped." For example, "Creedence Clearwater Revival - Who'll Stop the Rain.mp3" will become simply "ll Stop the Rain.mp3." I may implement a work-around in a future version of rbDJ. For now, I suggest you replace apostrophes in a song's filename with the backtick character, the character on that rarely-used key (in English, anyway) to the left of "1" and above "tab;" thus, "Who`ll Stop the Rain." As proof that this error is PHP's fault and not mine, go here: http://www.php.net/manual/en/features.file-upload.php ...and scroll down to the comment posted by "lobo235 at gmail dot com" on 4 January 2005. Also, by default, PHP doesn't like uploaded files larger than 2 megabytes, though your web server's administrator may have raised (or lowered) that limit. However, you can encode a four-minute song at 64kbps at under 2 megs, and it'll sound decent if you use a good MP3 encoder like LAME. http://lame.sourceforge.net Also note that radio.blog only likes songs encoded with a sampling rate of 44.1khz (44100 hz) or 22.05khz (22050 hz). This is not evident in its documentation. Songs encoded at other sampling rates will sound unnaturally sped up and "chipmunk-like." Instruct your members that they must encode their music at this sampling rate in order for it to work. If you've used radio.blog much before, you're familiar with how rb's music files have an odd ".rbs" extension. In reality, these files are simple MP3 files; radio.blog just likes them to have that ".rbs" extension for some reason. Anyway, it is not necessary to rename your MP3 files with this extension before you upload them; rbDJ will do that for you. Theoretically, rbDJ should have full support for songs with UTF-8 characters in the filename, especially if your server's PHP build supports the Multi-Byte String ("mbstring") library. However, radio.blog's support for non-ASCII filenames seems to vary by browser; on Safari, things work fine, but on Firefox or Internet Explorer, songs with non-ASCII characters will not load. INSTALLATION ------------ 1. Install radio.blog according to its directions and make sure it works. If you are integrating rbDJ with a forum or CMS, install and configure it and make sure that works too. 2. Decompress the rbDJ archive. The resultant directory (or "folder") will have a subdirectory in it entitled "configs". Look in that directory and find the configuration file that corresponds to how you want rbDJ to be set up. Copy that configuration file into the main rbDJ directory and rename it just "config.php". Now open the file you just named "config.php". This will allow you to configure rbDJ how you like it. It's a bit inelegant, but it should be self-explanatory. To change any of the values, ONLY modify the part of the line inside the quotes, and make sure the line ends with a semicolon (;). For example, to change the minimum registration day limit to 30, change the line $DJmindays="60"; to look like this: $DJmindays="30"; That's all. If you seem to be getting errors about your configuration file, make sure all of your values are inside quotes, and there's a ; at the end of each line. Save this file when you're done. 3. To avoid confusing rbDJ, delete all the songs from your "sounds" directory in your radio.blog installation on your web site. (You can upload them again using rbDJ.) 4. Upload the "playlist.php" file into the "sounds" directory in your radio.blog installation. There should already be a file named "playlist.php" there, so we want to overwrite that one with this new one, which is pretty much the same as the original one, but contains a few new lines of code to work better with rbDJ. (Both rbDJ and radio.blog will work if you skip this step, but you won't be able to preview single songs inside of rbDJ, so it's recommended.) 5. Upload the entire "rbdj" directory into your radio.blog directory. Do not upload the files alone; upload the entire directory. 6. Access "index.php" in your "rbdj" directory on your web site. Remember your "rbdj" directory is (or *should* be) inside your radio.blog directory. Log in with a username and password, and start rocking! 7. Optional: Customizing templates: rbDJ's appearance is spartan but functional. If you want to spruce up the look of rbDJ, modify the files in the "templates" directory . They are Smarty templates, so they're a bit different from plain HTML files, but if you have even the least bit familiarity with programming, you should be able to figure things out. To learn more about Smarty templates, check this out: http://smarty.php.net/docs.php Note that you can also convert rbDJ to another language just by changing the words and phrases in the template. (If you did a good job converting rbDJ to another language and want to share it with the world, please contact me!) 8. Optional: Preventing song theft: I'm not really sure how it happens, but sometimes people from outside of your web site seem to find your music and start "leeching" it. This can have a detrimental effect to your bandwidth if it happens too much. The two steps below will slow this leeching. Note that these steps are not specific to rbDJ, but should be taken by all radio.blog users. a. If you check out your "sounds" directory in a browser (for example: http:// mywebsite.xyz/radio.blog/sounds"), you'll probably see a "directory listing" with a list of all the files in that directory, ready to be nabbed. To stop folks from checking out your directory like that, simply create a simple web page, name it "index.html", and upload it into your "sounds" directory. Both radio.blog and rbDJ will ignore it. b. This one's a bit trickier. If your web host is running the Apache web server program, we can create a little script to block people from accessing the music files unless they are from your site. And while we're at it, because it's good practice, we'll stop people from stealing image, video, and other types of music files. SetEnvIfNoCase Referer "^http://mywebsite.xyz" local=1 SetEnvIfNoCase Referer "^http://www.mywebsite.xyz/" local=1 SetEnvIf Referer "^$" local=1 Order Allow,Deny Allow from env=local Obviously, you want to change "mywebsite.xyz" and "www.mywebsite.xyz" with whatever the actual URL of your web site is. If you want to allow access from other sites, create a new "SetEnvIfNoCase" line in exactly the same format as the first two, and put in those sites' addresses. See the long list of extensions on the line that begins with "