How to add more Flash players to the Audio module

This guide is for the audio-6.x-1.0-unstable4 version of the Audio module. It will probably work for other versions, but has not been tested, so use at your own risk.

This guide covers how to incorporate other Flash Audio players into the Audio module.

First of all, you should understand how the Audio module knows which Flash Audio players to work with.

Inside the audio.module is a function called _audio_player_build_list(). This function scans the /players folder for .inc files, and parses them to include into the Audio Settings page.

The .inc file is the key. You need to create a file named YOURPLAYER.inc (substituting YOURPLAYER with the name of the player you'd like to include) and save it in the players/ directory.

Here is a template for YOURPLAYER.inc:

<?php

function audio_YOURPLAYER_audio_player() {
  $items['YOURPLAYER'] = array(
    'module'      => 'audio',
    'title'       => t('YOURPLAYER Flash player'),
    'description' => t('YOURPLAYER description'),
    'url'         => t('http://www.YOURPLAYER.com/'),
    'preview'     => 'players/YOURPLAYER.png',
    'formats'     => array('wav', 'mp3'),
    'theme_node'  => 'audio_YOURPLAYER_node_player',
  );
  return $items;
}

function theme_audio_YOURPLAYER_node_player($node, $options = array()) {
  // make sure it's compatible with the flash player
  if (!audio_is_flash_playable($node)) {
    return NULL;
  }

  $options['soundFile'] = check_url($node->url_play);
  $url = base_path() . drupal_get_path('module', 'audio') .'/players/YOURPLAYER.swf';
  $flashvars = audio_query_string_encode($options);

$output = <<<EOT
<object type="application/x-shockwave-flash" data="$url" width="290" height="24" >
  <param name="movie" value="$url" />
  <param name="wmode" value="transparent" />
  <param name="menu" value="false" />
  <param name="quality" value="high" />
  <param name="FlashVars" value="$flashvars" />
  <embed src="$url" flashvars="$flashvars" width="290" height="24" wmode="transparent" />
</object>
EOT;

  return $output;
}

This code is taken directly from the 1pixelout.inc file (except the player is named YOURPLAYER).

As you can see, the file has two functions. One gives information about your player to the Audio module, the other one actually creates the HTML that will be embedded in the page. For the most part, each function requires only minor changes.

For the audio_YOURPLAYER_audio_player() function:
- Leave 'module' set to 'audio'
- 'title', 'description', and 'url' should be whatever seems reasonable (likely taken from your flash player's site)
- 'preview' is optional, but if you have one, I suggest putting it in the players/ directory
- 'formats': You can leave as is, but see "Handling other formats" below
- 'theme_node' should be set to the name of the function immediately following, without the "theme_" precursor ("theme_audio_YOURPLAYER_node_player" should be "audio_YOURPLAYER_node_player") - do a search-and-replace on the code and you'll do fine.

For the theme_audio_YOURPLAYER_node_player() function:
- You will probably want to change the width and height values
- You might change the name="wmode" value="transparent" values to a background color
- You can also include other HTML in this function (a link to the player's website for example). However, make sure you include the object tag, or else the Audio module will simply display a link to download the MP3.

Your Flash Object Directory

The easiest thing to do is to save a copy of the Flash object (e.g. YOURPLAYER.swf) in the Players directory, and simply change the filename accordingly. If you can't (or don't want to) do that (e.g. you have SWF Tools installed and want this to point to FlowPlayer), then change this line:
$url = base_path() . drupal_get_path('module', 'audio') .'/players/YOURPLAYER.swf';
...to point to where your .swf file is.

It's probably helpful to know about the drupal_get_path function:
http://api.drupal.org/api/function/drupal_get_path

This will make your life a little easier - if you know which module installed your Flash object, and where, you can just use this function to make sure the path is correct.

Handling Other Formats

If your Flash file can handle formats other than Audio, then just change this line:
'formats' => array('wav', 'mp3'),
...to include whatever formats you'd like. Do not include leading periods.

Next, make sure those formats are handled by the Audio module, by going here:
Administer > Site Configuration > Audio Settings
...and putting those formats into the "Permitted audio file extensions" field.

Skinning and Theme Overriding

Anything other than the most basic HTML output should ideally be handled by a theme override. Since it's handled at the theme level, it's much easier to (for example) have the Flash player's colors match the theme's colorscheme.

For the most part, Flash players handle skinning by passing values to the Flash object. What those values are, is dependent upon the Flash player that you use. Whatever they are, the easiest way to pass those values is to add them to the Options array, and let the default .inc function handle it.

Here is some useful code for your theme override function:

function YOURTHEME_audio_YOURPLAYER_node_player($node, $options = array()) {
  $newoptions['OPTIONNAME'] = 'OPTIONVALUE';
  $options = array_merge($newoptions, $options);
  return theme_audio_YOURPLAYER_node_player($node, $options);
}

Just replace YOURTHEME with your theme name, YOURPLAYER with your player name (as above), OPTIONNAME with whatever option your player accepts, and OPTIONVALUE with whatever value you'd like to assign.

As an example, here's a theme override for skinning the 1pixelout player:

function mytheme_audio_1pixelout_node_player($node, $options = array()) {
  // Set only the options we need here, send the rest to the default function
  $newoptions['text'] = '0xC0C0C0';
  $newoptions['bg'] = '0x333333';
  $newoptions['leftbg'] = '0x696969';
  $newoptions['rightbg'] = '0x000000';
  $newoptions['rightbghover'] = '0x696969';
  $newoptions['lefticon'] = '0xFFFFFF';
  $newoptions['righticon'] = '0xFFFFFF';
  $newoptions['slider'] = '0xFFFFFF';
  $newoptions['track'] = '0x696969';
  $newoptions['loader'] = '0xC0C0C0';
  $newoptions['border'] = '0x696969';
  $options = array_merge($newoptions, $options);
  return theme_audio_1pixelout_node_player($node, $options);
}

A good tutorial on how to do this is here:
http://www.innovatingtomorrow.net/2007/10/22/how-theme-1pixelout-flash-p...

Though the tutorial is geared towards the 1pixelout player, the concepts should be applicable to any Flash player that accepts options through flash variables (which is most of them). To find out what those options are, consult your Flash player's documentation.

Using this tutorial, it shouldn't be too difficult to incorporate whatever Flash player you'd like into the Audio module.

Happy coding!