A Django template tag for integrating a Flash based mp3 audioplayer

This blog entry was posted by peter on June 27, 2007.

It is tagged with audio, Django, Flash, mp3, and Python.

So far there are 9 comments. Feel free to add one.

The previous entry chronologically is instantplayer beta 1 released.


A Django application for integrating a Flash based mp3 audioplayer into templates using a custom template tag. It uses the flashplayer from 1pixelout and can be easily customized by template parameters.

Download

The audioplayer app is only available as a tarball. It contains the Django application and the flashplayer from 1pixelout. Also note the Changelog

GoogleCode SVN

The audioplayer app can also be checked out from the SVN at GoogleCode.

Installation

To install the audioplayer app, follow these steps:

  1. Unpack the downloaded tarball in your projects directory
  2. Add myproject.audioplayer“ to your INSTALLED_APPS variable
  3. Configure your webserver or urls.py to serve the Flash file player.swf found in the media/audioplayer subdirectory. By default the player is searched at {{ MEDIA_URL }}/audioplayer/player.swf but that can be changed (see below).

That’s it. The audioplayer does not use any models or views, only a custom template tag named audioplayer.

Using the audioplayer template tag

The audioplayer can be used in any template like this:

1
2
3
4
{% load audioplayer %}
# …
{% audioplayer file=file_url %}
# …

First load the audioplayer template tag library, then instantiate the player as often as you like, using different files and/or player configurations.

Here’s a live example:

Customizing the audioplayer

The audioplayer can be customized to fit your project’s needs.You can set looping, width, height and the colors for the various player areas like this:

1
{% audioplayer file=file_url,loop=True,autostart=True,bg=0xff000 %}

The following table contains the full list of supported parameters. The original can be found at 1pixelout_runtime. Please be aware that the original values for the autostart and loop has been pythonified: Instead of using yes and no the audioplayer tag can also use False and True.

ParameterDefaultDescription
file
    		The URL of the mp3 file
    playerUrlsee belowThe URL of the player.swf file
    autostartFalseThe player will automatically open and start to play the track (False|True)
    loopFalseThe track will be looped indefinitely (False|True)
    bg0xHHHHHHBackground colour option (where HHHHHH is a valid hexadecimal colour value such as FFFFFF or 009933)
    bgcolor0xHHHHHHBackground colour
    leftbg0xHHHHHHLeft background colour
    rightbg0xHHHHHHRight background colour
    rightbghover0xHHHHHHRight background colour (hover)
    lefticon0xHHHHHHLeft icon colour
    righticon0xHHHHHHRight icon colour
    righticonhover0xHHHHHHRight icon colour (hover)
    text0xHHHHHHText colour
    slider0xHHHHHHSlider colour
    loader0xHHHHHHLoader bar colour
    track0xHHHHHHProgress track colour
    border0xHHHHHHProgress track border colour
    width156The width of the player
    height18The height of the player

    Serving the Flash player

    By default the audioplayer tag uses the player.swf found at {{ MEDIA_URL }}/audioplayer/player.swf.

    To change that behaviour pass the URL of the player using the playerUrl parameter like this:

    1
    {% audioplayer file=file.mp3,playerUrl=/foo/bar/player.swf,loop=True %}

    Inserted code

    The following code is inserted by the audioplayer template tag based on the audioplayer/audioplayer.html template (the shown code is just an example and varies depending on your parameters):

    1
2
3
4
5
6
7
8
    <object type=“application/x-shockwave-flash” data=“/media/audioplayer/player.swf” width=“156” height=“18” class=“audioplayer”>
    <param name=“movie” value=“/media/audioplayer/player.swf” />
    <param name=“FlashVars” value=“height=18&amp;#38;bg=0xff000&amp;#38;slider=0xB29461&amp;#38;track=0xFFFFFF&amp;#38;righticon=0x666666&amp;#38;lefticon=0x666666&amp;#38;soundFile=%2Fmedia%2Faudio%2FSucker_Kings_-_Cab_Driver.mp3&amp;#38;loader=0xEEFFCC&amp;#38;rightbg=0xCCCCCC&amp;#38;bgcolor=0xFFFFFF&amp;#38;rightbghover=0xAAAAAA&amp;#38;autostart=no&amp;#38;text=0x4F4F4F&amp;#38;leftbg=0xEFEFEF&amp;#38;righticonhover=0x444444&amp;#38;border=0x00FF00&amp;#38;width=156&amp;#38;loop=yes” />
    <param name=“quality” value=“high” />
    <param name=“menu” value=“false” />
    <param name=“wmode” value=“transparent” />
    <param name=“bgcolor” value=“#FFFFFF” />
</object>

    Replacing the default code template

    The code shown above is read from the template audioplayer/audioplayer.html. You can provide a custom template to adopt the code to your needs. The template will be passed the following context variables:

    player_url
    The URL of the audioplayer.
    width
    The width of the player.
    height
    The height of the player.
    bgcolor
    The background color of the player.
    flash_vars
    The flashvars for the player.

    Flash vars format

    Internally the flash vars are encoded using the urlencode function from the urllib. Here’s an example of some flash vars after the encoding:

    1
    height=18&amp;bg=0xff000&amp;slider=0xB29461&amp;track=0xFFFFFF&amp;righticon=0x666666

    Unfortunately the ampersand “&” is not allowed in XHTML documents and needs to be encoded. Rather to encode it using the entity representation &amp; the unicode representation &38; is used, so the encoded flash vars look like this:

    1
    height=18&amp;#38;bg=0xff000&amp;#38;slider=0xB29461&amp;#38;track=0xFFFFFF&amp;#38;righticon=0x666666

    Autoescape considerations

    In order to play nicely with the new autoescape feature in the Django development version you need version >=0.2.2 of the audioplayer app.

    Up from this version the template tag marks the inserted code as safe and correctly respects the current autoescape value in the template context, which needs to be considered when you provide a custom audioplayer/audioplayer.html template.

    Alternatives

    JavaScript

    Instead of integrating the audioplayer using a template tag one could also use some JavaScript to add the player to the page. The easiest way to achieve this is to use the jQuery and the jQuery plugin jMP3.

    Other Flash players

    Besides the nice player from 1pixelout, there are several other Flash based audioplayers out on the web. Here’s a list of them:

    Changelog

    0.2.2

    • Adopted to autoescape feature in Django development version (tested with 0.97-pre-SVN-6977).
    • The inserted code is now marked as safe using the django.utils.safestring.mark_safe() method.
    • The current autoescape setting in the template context is now correctly passed to the context rendering the audioplayer.html.

    0.2.1

    • Ampersands (&) in the flashvars value are now replaced by the entity #&38; in order to produce valid XHTML code.

    0.2

    • The audioplayer is now really searched at {{ MEDIA_URL }}/audioplayer/player.swf as described in the documentation above.
    • The parameters autostart and loop are now pythonified as described in the documentation above. Any of no,false,False,yes,true,True can be used.
    • The inserted <object> code is now based on the template audioplayer/audioplayer.html.

    0.1

    Initial release.

    Comments

    peter said on August 26, 2007

    Test comment. No real content. Really. Nothing.

    Bernd said on October 06, 2007

    hello,

    really cool app. Yesterday I tried it, but I found 2 errors.

    1) your documentation says
    >> By default the audioplayer tag uses the player.swf found at
    >> {{ MEDIA_URL }}/audioplayer/player.swf.

    But in your code is:
    player_url = “%s/player.swf” % (settings.MEDIA_URL)

    2) your documentation says
    >> Please be aware that the original values for the autostart and loop has been
    >> pythonified: Instead of using yes and no the audioplayer tag uses False and True.

    But autostart/loops does only works, if I pass yes/no to the autostart/loop parameter, because urlencode writes True to the parameter string, if I pass True to autostart/loop parameter

    in your code:
    player_flash_params = urlencode(self.params)

    peter said on October 08, 2007

    @Bernd: Thanks for reporting those bugs. I have uploaded a new version which fixes the issues. The new version also uses a template for the inserted code.

    You can check the Changelog at the end of the blog entry for details.

    Bernd said on October 09, 2007

    Hello,

    really great, fast response and a new version.

    But now there is another input from me. I use Firefox with the “HTML Validator”-Extension. It shows an error an the page with the audioplayer.

    The line with the error is:
    <param name=”FlashVars” value=”height=30&bg=0xF7F7F7&slider=0x344CF7&track=0x777777&righticon…… />

    The clean-up-version of the extension look like this:
    <param name=”FlashVars” value=
    “height=30&amp;bg=0xF7F7F7&amp;slider=0x344CF7&amp;track=0x777777&amp;…

    It would be great to correct the char “&” and write the HTML-Entity instead the original character.

    Regards,
     Bernd

    peter said on October 09, 2007

    Hi Bernd,
    i fixed the entity replacement and uploaded a bugfix release. I tested it with the W3C validator and the player code validates now. Again the Changelog has some details.

    Hope this works for you.

    Bernd said on November 18, 2007

    Hello Peter,

    with the latest django-trunk, your last change doesn't work. I think it's because of the new autoescape-feature.

    I had to change the line:
    player_flash_params = urlencode(self.params).replace('&', '&#38;')
    to
    player_flash_params = urlencode(self.params)

    peter said on March 02, 2008

    I have created a new version which should fix the autoescape issues. Please see the changelog and the updated documentation for more info.

    The audioplayer was also moved to GoogleCode. Read about that here:
    http://pyjax.net/blog/1/2008/03/02/mo…

    Karl Peterson said on March 13, 2008

    Excellent! This is exactly what I needed. Is there any way to have multiple songs play? I know that the player.swf supports multiple mp3s. How can I input them? Thanks.

    If you'd like you can reply to http://kbpeterson(at)gmail.com

    Carlitos said on June 02, 2008

    Fantastic work! Before I ran into this code I was actually outputting the code to the audioplayer.swf by hand in the HTML template… but this is so much nicer! :-)

    However, there's a think I can't get to work. I'm trying to play a file that has a comma (“,”) as part of the filename, which is valid for Apache and my Kubuntu laptop, where this code lives.

    Could you help me with this, please? Is that something related to the autoescape feature, maybe?

    Thanks again, and have a nice day!

    Add a comment