NGS SAM Integrator




The NGS SAM Integrator is a WordPress Plug-In designed for users of Spacial Audio’s SAM Broadcaster Pro software.   It allows you to set up a section on your WordPress site which integrates directly with your SAM Broadcaster Pro software, allowing your visitors to make requests whether you are DJing live or not.

Before You Install the Plug-In

Before you install the WordPress plug-in, you will need to configure both SAM Broadcaster and your mySQL database to allow your webserver to access them.  It is highly recommended that you set up a mySQL user specifically for use by the plug-in.  This user only requires SELECT access on the songlist, requestlist, and queuelist tables of your SAM database.  It does not require any global access privileges, nor does it need to be able to modify any data in your database.   For security reasons, the plug-in will NOT allow you to use the “root” user, even if you have configured it to be allowed external access.

Adding the MySQL User

This needs to be done on the machine that is hosting your SAM Broadcaster Database.  For most users, this will not be the same as your web server.  These instructions will result in a user named “samweb” with the password “secret” being created.  Replace these with values of your own, especially the password.

  1. Open a Windows Command Line window
  2. Navigate to the “bin” folder of your MySQL installation (This will usually be something like c:\mysql\bin or c:\xampp\mysql\bin)
  3. You will open up the MySQL console using one of two different commands, depending on if you have a password set up on your “root” user.
    1. If you DO NOT have a password set, type mysql -u root 
    2. If you DO have a password set type mysql -u root -p and enter the password when prompted.

      You should see a prompt that says “mysql>”

  4. Type CREATE USER ‘samweb’@’%’ IDENTIFIED BY ‘secret';
     Note the semicolon (;) at the end of the command.   This command creates a new user named samweb who can access the database from any host with the password secret.  You can (and should) replace this username and password with ones of your own choosing.
  5. Type GRANT SELECT ON samdb.* TO ‘samweb’@’%';
    Once again, note that the command must end with a semicolon(;).   This command assumes that your SAM database is named samdb (the default) and that you used the username samweb in step 4.  There is no need to repeat the password as it was already set in step 4.

The result will be a user who has read-only access to your SAM database.  The details you used to create this user will be used to configure the plug-in after installation.

For more information on MySQL users and privileges, please see http://dev.mysql.com/doc/refman/5.1/en/adding-users.html.

It is also recommended that you take steps to secure your installation of mySQL before allowing external access by this, or any other application or user.   For information on how to secure your mySQL installation, please see http://www.mysql.com/why-mysql/white-papers/a-guide-to-securing-mysql-on-windows/.

There are lot of different options you configure in SAM Broadcaster related to how it handles incoming requests.  Most of these are fairly self explanatory and can (and should) be adjusted over time to best suit your own needs as well as those of your visitors.   I will only cover those settings which are necessary to allow the plug-in to function.

  1. In SAM Broadcaster, click File > Config and select Request Policy.
  2. Make sure that Enable Requests is checked.
  3. You will see a list entitled Only accept requests from these IP addresses.   The default IP addresses in that list are mostly associated with Audiorealm, which is the site that Spacial Audio uses to process requests if you choose not to process them yourself.  This plug-in processes all request internally so you will need to add your webserver’s IP address to this list.  It is recommended, when possible, that you use the IP address rather than the domain name here.   In some cases, the domain name may not work here, depending on your webhosting provider.
  4. For information on the additional Request Policy settings in SAM Broadcaster, please see your SAM Broadcaster documentation or integrated help files.

You will also need to ensure that your firewall and/or router are configured to allow incoming connections on the proper ports for MySQL and SAM Broadcaster.  By default, these ports are 1221 for SAM Broadcaster and 3306 for MySQL.

Once this is done, the hard part is out of the way.  Installation and configuration of the plug-in itself is very easy and straight forward.

Installing and Configuring the Plug-In

Approval of the plug-in for inclusion in the WordPress Plug-In Directory is still pending, so until that is approved, the plug-in must be installed manually.

  1. Download the NGS SAM Integrator Plug-In
  2. From your WordPress Admin Dashboard, select Plugins > Add New
  3. Select the Upload tab, click Choose File and locate NGS-SAM-Integrator.zip.
  4. Click Install Now
  5. Click Activate Plugin
  6. In your WordPress Admin Dashboard, under Settings, select NGS SAM Integrator
  7. In the top section, enter the IP Address and Port number where SAM Broadcaster is running.
  8. In the second section, enter the connection details for the MySQL database.  This is the database used by SAM Broadcaster, which is usually running on the same machine SAM Broadcaster is running on.
  9. In the bottom section, you can choose whether or not to show an estimated queue time and select the number of results to show on your request pages by default.   A higher number will mean more results being sent from your MySQL database at once, but a smaller number will result in more queries.
  10. The last two entries are the page ID numbers for the two request pages used by the plug-in.   If you leave these blank, the plug-in will automatically generate new pages when you save your settings and record the ID numbers here.   If you wish to set up your own custom pages, you can allow the plug-in to generate them automatically and then modify them, or you can set them up and then tell the plug-in what the ID numbers are.

WordPress Shortcodes

There are two WordPress Shortcodes which the plug-in uses to display the request lists.

[samplaylist] will display a list of all songs in your library, sorted by artist.

[samtoprequests] will show a list of all songs which have been requested at least once, sorted by the number of times it has been requested (most request first).

Support

Support is available through the WordPress Support forums at http://wordpress.org/support/plugin/ngs-sam-integrator.