Revision of Twine: HTML5 sound macros from Thu, 02/14/2013 - 08:41

Here's version 1 of some Twine macros to play sound files with HTML5 audio.

http://www.glorioustrainwrecks.com/files/TwineMacros-SoundMacros-1.0.0.txt

These macros accept either strings or string variables as their first argument. I recommend you set the filenames to specific variables and then use those as arguments to the macros.
<<playsound "carolofthebells.mp3" >> plays the file "carolofthebells.mp3" from the start.
<<loopsound $heartbeat >> starts playing $heartbeat from the start, over and over. Note: currently browsers are not that good at looping audio seamlessly - brief silences between loops may occur.
<<unloopsound $heartbeat >> makes $heartbeat no longer repeat when it finishes.
<<stopsound "birds.ogg" >> stops playing "birds.ogg"
<<pausesound "trees.ogg" >> pauses "trees.ogg" at its current location.
<<stopallsound>> stops all the sounds.

Important instructions:

  1. Included with the macros is a script that will preload all of the music files as soon as you begin the game. It does this by searching through all of your passages for anything that resembles a music filename - a string in either single or double quotes that ends with ".ogg", ".mp3", ".wav" or ".webm". Then, it will attempt to load that as a file. I consider this to be simpler and more desired behaviour than explicitly requiring you to put preloader macros at the start of the story, but bear this in mind when you write passages.
  2. For legal and free software advocacy reasons, the Apple and Microsoft browsers (Safari, Internet Explorer) do not support OGG format, whereas the cross-platform browsers (Opera, Firefox) do not support MP3. (Google Chrome supports both.) So, you may have to include your music file in both formats. How this will work is as follows: when the setup script finds a music filename, it first sees if it can play its file extension, and, if that fails, tries to find an identically named file with a file extension that it can play. (For instance, trying to play "woods.ogg" on Safari would cause it to open "woods.mp3", and trying to play "ghost.mp3" on Opera would make it open "ghost.ogg"). So, make sure different versions of the same sound have the same filename prior to the extension.
  3. Implementation-wise, this creates a global object called "Soundtracks" which stores Audio objects for every found sound file. I'm not sure if this is the most usable method just yet. This may change in future versions.

There's a lot that can be done to expand on this. Something I intend to add is a way to bind looping sounds to a specific passage tag. So, you could perhaps write <<tagsoundloop "trees" "Howling_Monkeys.mp3">> and then give a passage a tag of "trees", and it will keep looping "Howling_Monkeys.mp3" if you're at such a passage, and stop it when you leave. That will come later. Also on the list of possibilities: fading sounds in and out when they're stopped, and support for base64-encoded sounds (which no one except me will ever use).

Version history:

  1. 15-2-12 - Initial.

AttachmentSize
TwineMacros-SoundMacros-1.0.0.txt1.85 KB