STATIONPLAYLIST REQUEST SCRIPT USER GUIDE What is the StationPlaylist Request Script? The StationPlaylist Request Script provides listeners of your radio station the ability to search your music library and send a request to your station, right from your website. But it doesn't stop there. In addition to submitting a request, visitors can view upcoming requests as well. Further, an advanced function will randomly select names of some of the artists you have in your music library, and provide search links for you to place on your homepage. An option to place the search box on other pages of your website is also provided. This script queries your copy of StationPlaylist Studio Pro for the information needed, and visitors can interact to send their request to StationPlaylist Studio Pro from your website. From there, you will decide how you want to act on that request. See the Song Requester chapter in Studio's documentation for Studio configuration requirements. SCRIPT REQUIREMENTS To use this script, you will need StationPlaylist Studio Pro 5.01 or later, and a web server running PHP 5 or later. You will also need your StationPlaylist Studio Pro on a computer that is publicly accessible to the internet for both incoming and outgoing connection on a port you specify. The script will need to access this same port as well. If your ISP or web host blocks the port you specify on any part of this connection, the script will not be able to talk to StationPlaylist and it will not function at all. GETTING STARTED These next few steps should get you started with the basic setup in about 10 minutes. 1. Unzip the zip archive file to a folder on your local PC. Inside you will find the following files: build.php config.php footer.php function.php header.php reqform.php reqline.php request.php style.css 2. Open the config.php file in a text editor such as notepad. You will need to edit the following lines: $studiohost = "127.0.0.1"; // Domain name or IP address of SPS server $studioport = 443; // Port# assigned in SPS to listen for commands Replace 127.0.0.1 with your publicly accessible IP address. You can see this by loading www.whatsmyip.net in a web browser. If you don't have a static IP address arranged with your internet provider, this IP can change without notice. In this case, there are free and paid dynamic DNS solution providers such as www.noip.com. Make sure that you specify the same port as Studio Pro is configured to listen on, in Studio's Communications options / TCP Server. Note 1: It is recommended that you choose a port not commonly used by other applications. Note 2: Some website hosts only have ports 443 and 80 open for outbound script connections. Note 3: Some ISP's block inbound connections on port 80. 3. If you are behind a router, configure your router to use port forwarding, and forward traffic on the assigned port to the private IP of the computer on which Studio Pro is running. If the router is UPnP compliant, Studio will configure the router for you automatically. Otherwise please reference your router's documentation. 4. Upload the above files to your webroot directory. Once this is done, you should be able to access the request script by going to www.yourdomain.com/request.php where www.yourdomain.com is the actual domain of your website. You can test the installation of the script by browsing to the above address. If successful, you should see "No pending requests" under the Pending Requests heading. If you see an error message instead, then please read the troubleshooting section on installation below. USING THE SCRIPT You can test the communication with Studio Pro by performing a search for an artist or song title you have in your collection. 1a. Type part of an artist's name or song title in the search box and click search. 1b. Or click a letter of the alphabet to browse tracks with artists beginning with that letter. 2. Choose your request from the list by clicking the radio button next to your selection. This is a round circle to the left of the artist name. 3. Click the "submit your request" button. Once submitted, the page should display your request in the pending request list. Also, inside Studio Pro, pressing control+q will show you the pending requests. PERSONALIZATION Now that you have the script working, you may want to personalize it to integrate with your station's website. There are a few basic configuration options you can use to do this and some advanced functions available for integrating with other pages of your website. BASIC CONFIGURATION To configure the basic settings, perform the following steps: 1. Using a plain text editor like Notepad, open the config.php file in the folder where you unzipped the scripts and find the following lines. $namefield = 1; // Request listener name: 0=no, 1=yes, 2=required This line indicates whether or not you want the persons name, and if it is required. If you change this option to 2, then a request can not be submitted if there is no name in this field. A 0 hides the name field, and a 1 shows the name field. $locationfield = 1; // Request location: 0=no, 1=yes, 2=required This line works like the previous line, and is used to gather the listener's location, such as neighborhood, city, state, etc. $expire = 7; // Number of days to remember name and location. 0=just for the session This value specifies the number of days to remember the name and location as described above. The expiration date is extended each time the script is run, so the script will autofill the name and location fields each time it's run within the specified period. If the value is set to 0, it autofills during the current browser session. $requestsperhour = 4; // Max number of requests allowed per hour for each listener This indicates the maximum number of requests per hour you allow from each computer which is accessing your site. If you set this to 5, that computer can make 5 requests per hour. $requestsperday = 12; // Max number of requests allowed per day for each listener This value limits the number of requests per day. If you set this to 10, then the computer can only submit 10 requests per day. $sitename = ""; // Insert your station name between the quote marks The text between the quotes here will be used wherever this script references your station's name. $home = "/"; // Used to link to your homepage This is usually accurate, unless you are using a subdirectory for this script. If you are not sure if you need to change it, try the link when the scripts are installed, and change this value if necessary. $css = "style.css"; // Filename of an optional style sheet This references a style sheet. You can specify one you are already using for your website, or simply edit the included file to achieve the look you desire. $header = "header.php"; // Filename of an included header file (file may include PHP code) $footer = "footer.php"; // Filename of an included footer file (file may include PHP code) You can edit these lines to specify a header and/or footer file you are using, or edit the included files that are in the zip archive. The header will appear at the top of the request page and the footer will appear at the bottom of the page. $script = "request.php"; // Name of request script. Change this if file is renamed. Change this if you rename the request script or locate it in a subdirectory. e.g., If you place this script in a subdirectory called request and rename it to index.php, specify "request/index.php" in the above line. $banfile = ""; // Name of ban file (optional). One IP per line. Optionally, you can specify a ban file containing banned IP addresses, one IP address per line. Banned IP addresses will not be allowed to use the request script. Type the filename, including path if applicable, between the quote marks. $buildlib = 0; // Hours between local library rebuilds. 0=disabled, -1=manual rebuild The alphabet browse feature can download a lot of information from Studio. This may be a problem for slow internet connections. If clicking a letter of the alphabet takes too long, set this option to a non-zero value and the script will utilize a copy of the track library stored on the web server. This data needs to be downloaded from Studio periodically, often once a day. Set to a positive value, the request page will rebuild the library when a visitor loads the request script and the library has not been rebuilt for x hours. Set to -1, build.php needs to be run manually or by some other method, such as a scheduled task on the web server. $libdir = "library"; // Directory containing library files. Empty string "" to disable. If you've enabled the local library feature described above, you can specify a folder name in which these files will be stored. The default is to store them in a folder called "library" but this can be changed. If no folder name is supplied (nothing between the quote marks) then the files will be stored in the folder with the request script. 2. Once you have modified the request script's config.php file, re upload it to your web host. You can verify the changes by viewing your site. Please be sure to use the features that you have on the site, including the ones that you have changed. Note that the request limits may not take effect until the currently set limits expire. ADVANCED CUSTOMIZATION This section explains advanced features of this script intended for users who are very familiar with their web environment. You need to know how your web site is constructed and how to work with html and PHP to take full advantage of these features. Any page implementing one or more of these features must be treated as a PHP script by your web server. In nearly all cases, this is accomplished simply by giving the file a .php file extension. As a reminder, the request script and accompanying document is provided as is, and no support for your web server is provided by StationPlaylist. PLACING COMPONENTS ON OTHER WEB PAGES You may wish to place the pending requests list or the request form somewhere else on your site. To do this, you will need to know how to insert code snippets into your web pages. To use any of these advanced features, you will need to insert the following 2 lines at the top of the page: If the request script resides in a subdirectory under the page to which the component is being added, the above specifications must include the path, i.e., request/config.php for instance. ADDING THE SEARCH FORM Paste the following line at the point in the webpage where you want the form to appear. Again, prepend the path if the request script resides in a subdirectory. ADDING RANDOM ARTIST SEARCH LINKS You can have the script return a group of search links for randomly selected artists. To do this, insert the following line at the top of the page below the 2 include statements described above. The value specified after the $howmany= indicates the number of links you want returned. In the above line, this value is 3, but it can be any integer greater than 0 and less than the total number of artists in your music library. Then, where you want the links to appear, you will place the following lines in your document: Each line will give a different artist link. This is set up so that you can use each line to fill in the name of a random artist in a sentence or paragraph. All you need to do is insert one line at each point where you want to fill in an artist. Note that the indices [between the brackets] begin with 0 rather than 1, so in our example, there are 3 links returned, indexed as 0, 1, and 2. The links, when activated, will perform a search for those artists on the search page. DISPLAYING THE PENDING REQUESTS To display the pending requests, insert the following line at the point where you want to put the list of pending requests. TROUBLESHOOTING Here are some troubleshooting tips to help you diagnose some common configuration problems. TIMEOUT ERROR If you see a timeout or other error displayed under the pending request list, it means that the script is unable to communicate with StationPlaylist Studio Pro. There are a number of possible reasons for this. Check the following: * Make sure the IP address you specified in the config.php file is the public IP address of the computer on which Studio Pro is running. The local IP address will not work. * Verify that the port specified in the config.php file is the same as the port configured in the TCP settings of Studio Pro. * Confirm with your ISP and web host that you are allowed to open the port you have chosen and that it does not conflict with other port usage on the server. * Make sure that the port being used is not blocked by any firewall. * If the computer running Studio Pro is connected to a router, be sure that port forwarding has been set up properly. PHP ERRORS If you see some sort of PHP error in the request.php file, it likely means that the file has been corrupted somehow. Try reuploading the original file from the zip archive. If this problem occurs after a script update, make sure that all changed files associated with the script have been uploaded. These would include request.php and function.php. If the update requires that config.php be uploaded, make sure all configuration items have been modified appropriately in the config.php file prior to uploading. The following files are provided as templates and need not be uploaded with new updates: header.php footer.php style.css Likewise, the reqform.php file simply contains the search form and will probably not require any updates. If PHP errors occur in files other than those distributed with the script, (files you are adding advanced features to) check the inserted code snippets to make sure they are complete and that no typographical errors have been introduced into the code. Also make sure that file paths have been inserted if applicable. SUPPORT If the answer to your question or solution to your problem is not found in this document, support is provided through the StationPlaylist discussion group. You may join the StationPlaylist discussion group via email by sending a blank email to: StationPlaylist+subscribe@groups.io Or visit the discussion group website: https://groups.io/g/StationPlaylist Copyright 2010-2013 by Jeff Harris - Jeff@HookedOnThe.Net For script version 3.2 - 2013-02-24