From 5763388006489e1ae54601dd8d39f89392048cd3 Mon Sep 17 00:00:00 2001 From: ChapelR Date: Thu, 18 Jul 2019 14:30:15 -0400 Subject: [PATCH] prepping 2.0.0 excite --- docs/README.md | 34 +++++++++++------------ docs/v2.md | 75 +++++++++++++++++++++++++++++++++----------------- 2 files changed, 67 insertions(+), 42 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1098b64..910a2e9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ [Try out the demo.](./demo/ ':ignore') -HAL is an audio library for [Harlowe (v2.1.0 or higher)](https://twine2.neocities.org/) designed to give the format feature parity (or close to it) with [SugarCube's audio subsystem](http://www.motoslave.net/sugarcube/2/docs/#simpleaudio-api). HAL was designed from the ground up *specifically* for use with Harlowe, and is intended to be as easy to use as possible for novice programmers without compromising functionality. +HAL is an audio library for [Harlowe (v2.1.0 or higher)](https://twine2.neocities.org/) designed to give the format feature parity (or close to it) with [SugarCube's audio subsystem](http://www.motoslave.net/sugarcube/2/docs/#simpleaudio-api). This library was designed from the ground up *specifically* for use with Harlowe, and is intended to be as easy to use as possible for novice programmers without compromising functionality. ## Features @@ -15,7 +15,7 @@ HAL is an audio library for [Harlowe (v2.1.0 or higher)](https://twine2.neocitie ## Getting the Library -You can download any version of HAL from [here](https://github.com/ChapelR/harlowe-audio/releases). If you're just getting started, it's highly recommended that you grab the latest version. Once you've downloaded HAL, you'll need to read the [guide](#guide) or the [documentation](v2) to learn how to use it. +You can download any version of HAL from [here](https://github.com/ChapelR/harlowe-audio/releases). If you're just getting started, it's highly recommended that you grab the latest version. Once you've downloaded the library, you'll need to read the [guide](#guide) or the [documentation](v2) to learn how to use it. There are two main version of HAL. The latest version 2 release is recommended for most users. If you're already using version 1 in your project, you don't have to update if you don't want to and can instead grab the latest version 1 release. The version 1 docs are [here](v1). @@ -34,37 +34,37 @@ See [below](#guide) for a guide on the basics of using HAL. # Guide -This is a quick and dirty guide to getting HAL working. You're here for audio, and this guide aims to please. HAL has a lot of other nice features you may need to come to grips with later, but for now, we'll focus on the bare minimum you'll need to know to take your story from a boring, soundless husk to grooving like it's 1999. +This is a quick and dirty guide to getting HAL working. You're here for audio, and this guide aims to please. This library has a lot of other nice features you may need to come to grips with later, but for now, we'll focus on the bare minimum you'll need to know to take your story from a boring, soundless husk to grooving like it's 1999. > [!NOTE] -> This guide is intended to get users up and running with HAL quickly and without too much fuss. It covers v2.0.0 and higher of HAL, [for v1, check out its docs](v1). For detailed reference documentation for v2, [click here](v2). +> This guide is intended to get users up and running with HAL quickly and without too much fuss. It covers v2.0.0 and higher, [for v1, check out its docs](v1). For detailed reference documentation for v2, [click here](v2). ## Installing HAL in Twine 2 To install HAL, all you need is the code, which you can get [on the releases page of the repo](https://github.com/ChapelR/harlowe-audio/releases). You should choose the version with the highest version number. Download the `harlowe-audio.zip` file and unzip it. There should be three files, `harlowe-audio.min.js`, `harlowe-audio.min.css`, and `LICENSE`. Open the `harlowe-audio.min.js` file in a text editor, copy all of the contents, and paste it into your story JavaScript area in Twine 2. To find the story JavaScript area, click the up arrow next to your story's name in the editor (bottom left-hand side), then click the appropriate menu option. -The story JavaScript menu option in the Twine 2 editor. +The story JavaScript menu option in the Twine 2 editor. You'll then do the same thing with the `harlowe-audio.min.css` file, pasting it into the story Stylesheet area instead. -The story Stylesheet menu option in the Twine 2 editor. +The story Stylesheet menu option in the Twine 2 editor. > [!TIP] > You should open these files in a **text editor**, not a word processor. Any text editor you have, like notepad, will work fine for this. Opening the file in a word processor may cause the code to stop working, as they sometimes convert certain characters into other characters on loading files—like turning normal quotes ("...") into curly quotes (“...”)—that can mess up programming code. Once all the code is in place, try playing your story. If you see a gray sidebar on the left with a white arrow at the top, and you don't encounter any errors popping up, you've installed it right! -If you have a sidebar like this and no errors, HAL has been installed correctly. +If you have a sidebar like this and no errors, HAL has been installed correctly. ## Defining Tracks -There are a few ways to define tracks in HAL, but the easiest (and recommended) way is with a *special passage* called `hal.tracks`. +There are a few ways to define tracks, but the easiest (and recommended) way is with a *special passage* called `hal.tracks`. > [!TIP] > **What is a Special Passage?** > A special passage is a concept from Twine 1 and SugarCube where certain passages with special names have meaning to the story format. Harlowe doesn't use special passages (though it does have [special tags](https://twine2.neocities.org/#section_passagetag)). All you need to know to create a special passage is what name to give it. So to make the special passage, create a new passage in your story and give it the name `hal.tracks`. -An example of the tracks special passage. +An example of the tracks special passage. In this special passage you'll define each track on its own line. Tracks require a name and a list of URLs that point to audio files (that means they end with an audio extension, like `.mp3` or `.ogg`). You can give a track a number of source URLs; if you do, they should be the same track just in different file formats. If you only want to use one file format, `.mp3` is the safest bet. If you have the capability to create duplicates of the track in different formats, including both `.mp3` and `.ogg` versions is recommended, as that combination will give you the maximum possible browser support. @@ -87,7 +87,7 @@ On a basic level, all you need to do to play a track is have this code in a pass This is the `(track:)` macro, and you give it the name of a track you've defined and a command to perform. Some commands accept additional arguments, which you can just pass to the macro after the command name. For example, to set a track to loop, you'd write `(track: 'que-pena', 'loop', true)`. This is because the *loop command* accepts an argument, which should be boolean `true` or `false`; `true` to set the track to loop, `false` to stop it from looping. -The lion's share of commands in HAL don't require any arguments, and very few commands require more than one, but when they do, they have to be given to the macro in the correct order, so you will need to check the docs for those. +The lion's share of commands don't require any arguments, and very few commands require more than one, but when they do, they have to be given to the macro in the correct order, so you will need to check the docs for those. If you just want a looping background track and that's it, define the track in the `hal.tracks` special passage, then place the following code in a [`startup`-tagged passage](https://twine2.neocities.org/#passagetag_startup) or in your first passage: @@ -99,11 +99,11 @@ If you just want a looping background track and that's it, define the track in t ``` > [!NOTE] -> When you write one of HAL's macros in the Twine 2 passage editor, it will show up colored in red like macros that don't exist. It is not possible for a library like HAL to edit Harlowe's syntax highlighting feature, so this is unfortunately impossible to fix. Just know that it's expected behavior and doesn't mean you did anything wrong. +> When you write one of HAL's custom macros in the Twine 2 passage editor, it will show up colored in red like macros that don't exist. It is not possible for a library like this to edit Harlowe's syntax highlighting feature, so this is unfortunately impossible to fix. Just know that it's expected behavior and doesn't mean you did anything wrong. ## Examples -Now that you've got HAL installed and you know how to define a few tracks and play them, we'll cover a bunch of common use-cases here. To see more complex examples and use-cases, and learn more about what you can do with HAL, look at the [reference documentation](v2). +Now that you've got HAL installed and you know how to define a few tracks and play them, we'll cover a bunch of common use-cases here. To see more complex examples and use-cases, and learn more about what else you can do, look at the [reference documentation](v2). ### Defining Tracks with Absolute URLs @@ -127,7 +127,7 @@ There are about a thousand reasons you *don't* want to use absolute URLs, even t - If the file is on the file system, users who download your game are going to have to go and place those files in exactly the same places on their systems. E.g., in the example above, a user would have to take your audio folder and literally manually place it in `C:` in a folder called `twine` or the audio just won't work. - If the file is hosted on the web and served via `http://` or `https://`, your game will require a web connection for audio, even when it's being played offline. -- Whatever hosting service you use probably either serves an audio player rather than a song, or even if it does serve a song, it's probably against the Terms of Service of that website to *hot-link* to it. (Hot-linking is using someone else's website to host files for your website, and [it's widely frowned upon](https://tvtropes.org/pmwiki/pmwiki.php/Main/HotlinkedImageSwitch).) +- Whatever hosting service you use probably either serves an audio player rather than a file, or even if it does point to a file, it's probably against the Terms of Service of that website to *hot-link* to it. (Hot-linking is using someone else's website to host files for your website, and [it's widely frowned upon](https://tvtropes.org/pmwiki/pmwiki.php/Main/HotlinkedImageSwitch).) - Relative URLs work basically everywhere, except, ironically, the two places arguably most important to Twine authors, in the Twine 2 application and on [philome.la](http://philome.la/), a free Twine game hosting service. In the big scheme of things, unless you plan to upload to [philome.la](http://philome.la/), I recommend relative URLs, warts and all. @@ -143,11 +143,11 @@ que-pena: ./audio/que-pena.mp3, ./audio/que-pena.ogg Translation: `./` means to look in the current folder the current HTML file is in. So the file `./audio/beep.mp3` means that we look in our current folder for a folder named `audio` and look in *that* folder for our `beep.mp3` file. In other words, the folder containing our game looks like this: -Our folder containing our Twine project. +Our folder containing our Twine project. Then, the inside of that `audio` folder looks like this: -Inside the audio folder. +Inside the audio folder. When we want to share our game with friends, all we have to do is zip this folder up and email it. Or rename the game's HTML file to `index.html` and drop it on [itch.io](https://itch.io/). Or drop the whole folder onto your website (depending on how its made and where its hosted). Or send it through [web2executable](https://github.com/jyapayne/Web2Executable) to make it into a `.exe` file. In other words, its ready for anything. Except, as mentioned in the previous example, [philome.la](http://philome.la/) and, more distressingly, the Twine 2 app. @@ -246,6 +246,6 @@ You can wrap the `(track:)` macro to start playback of a track inside a `(link:) ## This Is Only the Beginning -HAL supports many other features, including master audio controls, playlists, and audio groups, and there are many other track commands you can use. You can also change HAL's configuration settings, use JavaScript event handlers to plug into various audio events and even edit the sidebar to display a menu +HAL has many other features, including master audio controls, playlists, and audio groups, and a variety of commands for all of it. You can also change the library's configuration settings, use JavaScript event handlers to plug into various audio events and even edit the sidebar to display a menu. -To learn more, check out [HAL's documentation](v2). It's a bit drier and more technical than this guide, but it's worth reading if you have grander designs than what's been covered here. \ No newline at end of file +To learn more, check out [the reference documentation](v2). It's a bit drier and more technical than this guide, but it's worth reading if you have grander designs than what's been covered here. \ No newline at end of file diff --git a/docs/v2.md b/docs/v2.md index 934141d..ea77b24 100644 --- a/docs/v2.md +++ b/docs/v2.md @@ -8,7 +8,7 @@ This is an audio library designed for the [Twine 2](https://twinery.org/) story **Why a Second Major Version?** -HAL v2 fixes some of the issues of HAL v1, but the biggest change is the addition of macros and special passages to create a more user-friendly coding experience. JavaScript APIs are largely still available and similar to their v1 counterparts, though many have changed, so you'll want to review the documentation even if you're familiar with HAL v1 and planning on sticking to JavaScript. +HAL v2 fixes some of the issues of HAL v1, but the biggest change is the addition of macros and special passages to create a more user-friendly coding experience. JavaScript APIs are largely still available and very similar to their v1 counterparts, though some *have* changed in ways that may be counter to your expectations, so you'll want to review the documentation even if you're familiar with HAL v1 and planning on sticking to JavaScript. **What Else Should I Know?** @@ -18,7 +18,7 @@ This library is free and dedicated to the public domain. That means you don't ne **I'm Having Trouble** -The best place to ask for help if the issue is on your end is [the Twine Q&A](https://twinery.org/questions/), [the Subreddit](https://www.reddit.com/r/twinegames/), or [the Discord server](https://discordapp.com/invite/n5dJvPp). If you suspect that the problem is in the code or otherwise on my end, [open an issue](https://github.com/ChapelR/harlowe-audio/issues/new). +The best place to ask for help if the issue is on your end is [the Twine Q&A](https://twinery.org/questions/), [the subreddit](https://www.reddit.com/r/twinegames/), or [the Discord server](https://discordapp.com/invite/n5dJvPp). If you suspect that the problem is in the code or otherwise on my end, [open an issue](https://github.com/ChapelR/harlowe-audio/issues/new). **Donate** @@ -29,24 +29,26 @@ The best place to ask for help if the issue is on your end is [the Twine Q&A](ht ### Installation -All you need to install this library is the code. Download the most recent version of HAL here, on the [releases page](https://github.com/ChapelR/harlowe-audio/releases). If decide to edit the code or need to pen it to copy and paste it into your IDE, be sure to open it and mess with it in a text editor, *not* a word processor. How you add this code to your project will depend on the compiler and IDE you use. +All you need to install this library is the code. Download the most recent version of HAL here, on the [releases page](https://github.com/ChapelR/harlowe-audio/releases). If you need to open one of the files to copy and paste it into your IDE or to make edits to the code, be sure to use a text editor, *not* a word processor. -**In Twine 2 (online or standalone)**, copy and paste the code in `harlowe-audio.min.js` into your [Story JavaScript area](https://twinery.org/wiki/twine2:adding_custom_javascript_and_css), and the code in `harlowe-audio.min.css` into your Story Stylesheet area. +Once you have the code, how you add it to your project will depend on the compiler and IDE you use. -**In Tweego or Entwine/Grunt-Entwine**, include the files in your command-line options or in your source code directory as appropriate. Remember to watch your file order, and refer to your compiler's docs if you need help. +- **In Twine 2 (online or standalone)**, copy and paste the code in `harlowe-audio.min.js` into your [Story JavaScript area](https://twinery.org/wiki/twine2:adding_custom_javascript_and_css), and the code in `harlowe-audio.min.css` into your Story Stylesheet area. -**In Twee2**, create a special passage with the `script` tag and place the JavaScript code in that passage, and do the same thing with the CSS and a `stylesheet` tag. Refer to its [docs](https://dan-q.github.io/twee2/documentation.html#twee2-syntax-special-passages) for more. +- **In Tweego or Entwine/Grunt-Entwine**, include the files in your command-line options or in your source code directory as appropriate. Remember to watch your file order, and refer to your compiler's docs if you need help. -**In Extwee**, you need to create special `script`- and `stylsheet`-tagged passages in your Twee code in much the same way as in Twee2. +- **In Twee2**, create a special passage with the `script` tag and place the JavaScript code in that passage, and do the same thing with the CSS and a `stylesheet` tag. Refer to its [docs](https://dan-q.github.io/twee2/documentation.html#twee2-syntax-special-passages) for more. -**In other compilers or IDEs**, you'll need to refer to your program's documentation for how to add JavaScript and CSS code. +- **In Extwee**, at time of writing, you need to create special `script`- and `stylsheet`-tagged passages in your Twee code in much the same way as in Twee2. Future versions of Extwee may add directory support similar to Tweego/Entwine. + +- **In other compilers or IDEs**, you'll need to refer to your program's documentation for how to add JavaScript and CSS code. ## Overview -HAL v2 allows authors to use either a simple JavaScript-based API or a set of custom macros for most operations. There are a handful of operations that can only be performed using the JavaScript API, but these are rare and probably not a major consideration for most authors. I recommend using whichever one you prefer. +HAL v2 allows authors to use either a (simple) JavaScript-based API or a set of custom macros for most operations. There are a handful of operations that can only be performed using the JavaScript API, but these are rare and probably not a major consideration for most authors. I recommend using whichever one you prefer. > [!WARNING] -> HAL relies on a hack to gain access to Harlowe's `Macros` API, and uses other undocumented features of Harlowe's engine. This means that, particularly regarding custom macros, it's possible that future releases of Harlowe could break certain parts of HAL. While I'll always try to stay on top of fixes, it's possible that certain parts of the library may stop working. +> HAL relies on a hack to gain access to Harlowe's `Macros` API, and uses other undocumented features of Harlowe's engine. This means that, particularly regarding custom macros, it's possible that future releases of Harlowe could break certain parts of HAL. While I'll always try to stay on top of fixes, it's possible that certain parts of the library may stop working with these future versions. > [!TIP] > HAL custom macros will show up in red in the Twine 2 passage editor, as if they don't exist. This is normal. @@ -75,15 +77,15 @@ HAL comes with the following custom macros: **Syntax:** `(newtrack: name, source [, source...])` -This macro is used to [define a track](#defining-tracks). You must give the track a name and at least one source URL that points to an audio file. You can give multiple source files to improve browser support. +This macro is used to [define a track](#defining-tracks). You must give the track a name and at least one source URL that points to an audio file. You can give a track multiple source files to improve browser support. **Arguments:** - `name` the name to give the track. - `source` at least one source URL must be passed to the macro. ``` -(newTrack: 'beep', './audio/beep.mp3', './audio/beep.ogg') -(newTrack: 'que-pena', './audio/que-pena.mp3', './audio/que-pena.ogg') +(newtrack: 'beep', './audio/beep.mp3', './audio/beep.ogg') +(newtrack: 'que-pena', './audio/que-pena.mp3', './audio/que-pena.ogg') ``` #### The `(newplaylist:)` Macro @@ -307,7 +309,7 @@ See the [Additional JavaScript Features](additional-javascript-features) section HAL has a variety of configuration options users can alter to fine tune the library to meet their needs. These options can be set using a *special passage*, which is a normal passage with a specific name that has meaning to the library. The special passage for configuring HAL must be named `hal.config`. -An example of a configuration special passage. +An example of a configuration special passage. Each option is a property/value pair on its own line, with the property name appearing on the left, a colon, and then the property's value. For example, to set HAL's sidebar to start opened, you'd type: @@ -338,10 +340,11 @@ Below are a list of the options you can set in your configuration passage and th |`persistPrefs`|`true`|`true` or `false`|The master volume and mute are considered user preferences, in that they are intended for users to adjust. You can use this option to cause changes to these settings to be saved and restored from local storage. For example, if the user sets the master volume to `0.3`, then closes the game, the master volume will be `0.3` rather than the `startingVol` next time they play the game.| |`globalA`|`true`|`true` or `false`|By default, and throughout this guide, the JavaScript API is sent to the global scope as `A`, matching HAL v1 and Howler for Harlowe's way of doing things. If you don't want that, or if the `window.A` name is already taken, you can find everything at `Chapel.Audio` instead.| |`showControls`|`true`|`true` or `false`|This library includes a control panel (as a sidebar) for users to control the master volume and mute state. You can determine whether or not you want to use it or roll your own (or not include options, you Philistine) with this option. If set to false the sidebar, controls, and associated APIs will be unavailable in your game.| -|`sidebarStartClosed`|`true`|`true` or `false`|The sidebar slides in and out from the side of the screen. By default it starts closed (taking up very little space) and needs to be opened by the user to be used. If you'd rather it start open, schange this setting to `false`.| +|`sidebarStartClosed`|`true`|`true` or `false`|The sidebar slides in and out from the side of the screen. By default it starts closed (taking up very little space) and needs to be opened by the user to be used. If you'd rather it start open, change this setting to `false`.| |`volumeDisplay`|`true`|`true` or `false`|Determines whether a text readout of the current volume is displayed next to the volume control.| |`trackLoadLimit`|`500`|A number of milliseconds.|Use this option to set a tolerance (in MS) for how long the preloading function will wait attempting to load a single track before moving on. In combination with the below option, this setting should be used to make sure the game doesn't just hang forever on slower connections.| |`totalLoadLimit`|`8000`|A number of milliseconds.|Use this option to set a tolerance (in MS) for how long the preloading function will wait attempting to load all of the tracks before dismissing the load screen. In combination with the above option, this setting should be used to make sure the game doesn't just hang forever on slower connections.| +|`debug`|`false`|`true` or `false`|Logs a bunch of debug info to the console as HAL does its thing. Useful for writing extensions and otherwise hacking on HAL, should not be used for much outside of that. You definitely don't want it on when you ship your game.| ## Defining Tracks @@ -357,7 +360,7 @@ Once you've got your source URLs squared away, there are three ways to define a The recommended way to define your tracks is through a special passage called `hal.tracks`. -The tracks special passage. +The tracks special passage. After creating a passage and naming it `hal.tracks`, you can type in the name of the track, a colon, and then a list of source URLs separated by commas. @@ -1149,7 +1152,7 @@ Methods: ## Defining Playlists -You can define playlists using the `(newplaylist:)` macro or the `A.createPlaylist()` method. A playlist is an ordered collection of tracks used to play those tracks one after the other. Playlists can also be shuffled and can be looped--a playlist loop differs from a track loop: the playlist will play all of its songs through once and then start over from the first cong when looped. +You can define playlists using the `(newplaylist:)` macro or the `A.createPlaylist()` method. A playlist is an ordered collection of tracks used to play those tracks one after the other. Playlists can also be shuffled and can be looped--a playlist loop differs from a track loop: the playlist will play all of its tracks through once and then start over from the first track when looped. Playlists differ from [groups](#defining-groups) in that groups are intended to create distinct audio subsets--music, sound effects, etc, that can be controlled in unison, while playlists are tracks that are meant to be played in some sort of order together. @@ -1428,6 +1431,17 @@ Methods: +### Other Playlist Commands + +There are two other playlist commands: `volume` and `mute`. These commands run the indicated command on each member track in the playlist. + +|Command|Description|Macro Example|JavaScript Example| +|---|---|---|---| +|`mute`|Mutes or unmutes every track in the playlist.|`(playlist: 'bgm', 'mute', true)`|`A.playlist('bgm').mute(true)`| +|`volume`|Sets the volume level of every track in the group.|`(group: 'bgm', 'volume', 0.5)`|`A.playlist('bgm').volume(0.5)`| + +Generally, groups are the preferred method for handling these sorts of situations, but if all the tracks are already in a playlist, you don't need to create a group just for this. Still, note that playlists are **not** groups—use groups unless you *need* some sort of ordered playback. + ## Defining Groups Groups are ways to collect and organize tracks, but should not be confused with [playlists](#defining-playlists). These are designed to allow you to select and control a large number of tracks and do something to them. The methods used by groups are very similar to some of the track methods, but as said, do something to all of them at once. @@ -1782,7 +1796,7 @@ Then: ### Looping Background Music -The `.loop()` method can be used to make music loop. If all you're after is a a backing track, this is all you need: +The `track#loop()` method can be used to make music loop. If all you're after is a a backing track, this is all you need: @@ -1850,9 +1864,9 @@ A.track('cool-song').fadeOut(6); -This will fade the song out over six seconds and stop it when the fade is over. +This will fade the track out over six seconds and stop it when the fade is over. -To fade one song out and another one in: +To fade one track out and another one in: @@ -1939,7 +1953,7 @@ Then: -The `.random()` method returns one random track from the playlist, and you can then use any [track methods](#track-methods) on it. +The `playlist#random()` method returns one random track from the playlist, and you can then use any [track methods](#track-methods) on it. ### Playing Sounds when Links are Clicked @@ -2124,7 +2138,7 @@ Makes the panel visible after hiding it. > [!DANGER] > You should **always** define your menu links Story JavaScript, or your compiler's equivalent script section, never in passages. -This API allows you to add links to the sidebar as a 'story menu', similar to what can be done in SugarCube. THese links can be used to navigate to a passage, run a JavaScript function, or both. They can be hidden, shown, toggled, and removed at any time. +This API allows you to add links to the sidebar as a 'story menu', similar to what can be done in SugarCube. These links can be used to navigate to a passage, run a JavaScript function, or both. They can be hidden, shown, toggled, and removed at any time. --- @@ -2229,9 +2243,12 @@ This method removes a story menu link. If there are multiple links with the same There are two kinds of events that are triggered by HAL--events triggered on the document *only* and events triggered on *both* the track element and the document. +> [!NOTE] +> Track event handlers defined via HAL's methods are always namespaced `.userland` and any namespaces you attempt to add are stripped. This is to protect the events used internally by the library. If you need more access, you can define the events on the appropriate elements yourself. + #### Track Event Methods -There are two track event methods you can use; `.on()` and `.one()`. The former triggers a handler each time the indicated event occurs, the latter triggers a handler only once. These methods can only be used with [track events](#list-of-track-events). +There are three track event methods you can use; `track#on()`, `track#one()`, `track#off()`. The former triggers a handler each time the indicated event occurs, the latter triggers a handler only once. These methods can only be used with [track events](#list-of-track-events). ```javascript A.track('some-song').one(':volume', function () { @@ -2247,9 +2264,13 @@ A.track('some-song').on(':volume', function () { }); ``` +```javascript +A.track('some-song').off(':volume'); // remove user defined events from the `:volume` event on this track +``` + #### Global Event Methods -As with track event methods, there are two: `A.on()` and `A.one()`. These event methods monitor *all* tracks for events, and also monitor for [master audio events](#list-of-master-audio-events). +As with track event methods, there are three: `A.on()`, `A.one()`, and `A.off()`. These event methods monitor *all* tracks for events, and also monitor for [master audio events](#list-of-master-audio-events). ```javascript A.one(':volume', function (ev) { @@ -2265,9 +2286,13 @@ A.on(':volume', function (ev) { }); ``` +```javascript +A.off(':volume'); // remove user defined events from the global `:volume` event +``` + #### List of Track Events -These events are triggered on both the document and the track element. The track's definition is available as `.track`. These events may be used with `.on()` and `.one()` to listen for events on specific tracks, or with `A.on()` and `A.one()` to listen for events on any and all tracks. +These events are triggered on both the document and the track element. The track's definition is available as `.track`. These events may be used with `track#on()` and `track#one()` to listen for events on specific tracks, or with `A.on()` and `A.one()` to listen for events on any and all tracks. | Event | Description | | --- | --- |