How to add Background Audio and Sound Bites to your Twine game

### DISCLAIMER

This is simply one of the many ways to add audio to Twine. There may be better ways to add audio and easier ways to manipulate audio files than this. I am a beginner in Twine and this is the first method I stumbled upon and understood quickly. I am using the Harlowe story format and its Audio Library.

## Preparation

### HARLOWE

#### What is Harlowe?

Harlowe is one of the many story formats offered by Twine. Each format has its pros and cons and is geared towards a certain audience. Harlowe is the default story format and is often recommended as a beginner friendly story format.

#### Harlowe Audio Library

For this tutorial, I will be using the Harlowe Audio Library (HAL) to add audio and sound bites to the game. Since Harlowe does not natively support audio files, this audio library must be downloaded and installed before use,

#### How to install Harlowe Audio Library (HAL)

The Harlowe Audio Library (HAL) wiki has its own set of documentation and instructions if you wish to follow. These are necessary steps:

1. Download the **latest** 'harlowe-audio.zip' from their github page.
2. Unzip the file. There should be 3 files present. **harlowe-audio.min.js** & **harlowe-audio.min.css** are the only files we are interested in.
3. Open the **harlowe-audio.min.js** in a text editor (preferably notepad) and copy all of its contents.
4. Open your Twine game. Click on the game name on the bottom left (next to the house). Select **Edit Story JavaScript** from the menu and paste the copied contents.Menu option to select
5. Do the same thing for the **harlowe-audio.min.css** file, pasting its contents into **Edit Story Stylesheet**.
6. Once all of these steps are done, test out the game. There should be a gray sidebar on the left and no errors. If you are confronted with any errors refer to the official guide for more details.

### JUKEHOST

#### What is Jukehost?

Jukehost is an audio hosting site that allows for direct links or an *Absolute URL* to the audio files you wish to use. An absolute URL tells the browser exactly where to find the file.

#### Why use Jukehost?

Harlowe Audio Library takes two types of Audio Track URLs; Absolute URLs or Relative URLs.

Relative URLs are basically file paths to local audio tracks on your computer. Example, "C:\Users\John\Downloads\ElevatorMusic.mp3". The problem with these is that any movement or renaming of the file will give an error and require a change of the path. Additionally, if you ever want to share the game with somebody, all audio files and any other local assets the game uses must be shared with the main game file. This creates new Relative URLs for each file and when dealing with multiple audio tracks, this becomes quite a hassle.

Absolute URLs allow us to upload audio tracks to the internet. This creates a URL that will not change no matter what computer the main game file is on. This way the game developer simply needs to add the Absolute URL once and then forget about it.

While the use of this site is not exactly necessary, it makes the process a whole lot simpler and less prone to errors. There may be other sites that do the same, but this is the one I found easiest to use. Example of Absolute URL: https://audio.jukehost.co.uk/YwfJCnMKV8FfPgVrEl1bz1bix2fylmXI.mp3

**NOTE:** When using other hosting sites, you need to make sure the link to share the track ends in the tracks file format. For example, when I upload an mp3 file to Jukehost, the link that I use to share will also end in .mp3, this is what an Absolute URL is.

#### How to use Jukehost?

The website is very simple and free to use. You simply need to:

1. **Register** for an account.
2. **Verify** your account using an email.
3. Log into your account and click on **Library>Upload.**
4. Once the upload is complete, click on **Home,** on the home page you'll see a **View your Library** option. Click on it.Click on 'View your Library'
5. Click on the *copy* icon next to the track you wish to use and you are done.

**NOTE:** The copied link will not have the file format attached to the end. You will need to manually add your file format. For example, if the audio track is an **mp3** file, you will need to add **.mp3** to the end of its link when pasting. Similarly, a **wav** file will require a **.wav** to the end.

## Adding tracks to Twine

Now that all the preparation is out of the way, this is the easy part.

#### Adding tracks

Create a special passage and name it **hal.tracks**. **The passage must be named this.** This passage will exclusively hold all tracks we wish to use, it will be used to assign names to each track's absolute URL.

Here you will assign names to an absolute URL. For example, if I wanted to add background music and its URL was https://audio.jukehost.co.uk/YwfJCnMKV8FfPgVrEl1bz1bix2fylmXI.mp3. I would put

```
bgMusic: https://audio.jukehost.co.uk/YwfJCnMKV8FfPgVrEl1bz1bix2fylmXI.mp3

```

This assigned the name *bgMusic* to the URL, to reference this track in other passages we will now use the name *bgMusic* rather than its URL. *bgMusic* can be replaced with any name you wish to use as long as it has not been used for another track. And just like this you can list out the rest of the tracks and add more as you make your game.

Continue to add more tracks

**REMEMBER TO ADD THE FILE FORMAT TO THE END OF THE URL. THE LAST TWO URLS IN THE ABOVE IMAGE DO NOT HAVE A FILE FORMAT ADDED TO THEIR URLS AND WILL GIVE AN ERROR UPON PLAYING THE GAME. BOTH THESE URLS SHOULD HAVE .mp3 AT THE END.**

## Playing tracks

Harlowe Audio Library uses the macro *(track: )* in order to play/pause and manipulate tracks. In its simplest form, in order to play a track you have to write:

```
(track: 'track-name', 'play')

```

This will start playing a track as soon as you reach its passage. Advancing from this passage will not end the track and playing another track will play both tracks. To stop a track, the track must either end or replace 'play' with the 'stop' command. Here is a list of examples the wiki uses to explain basic commands.

Additionally, there are ways to stop all tracks at once, wrap the *track* macro in an if statement, loop tracks, play tracks when hovering or clicking on a link, and many more when pairing with the default Harlowe macros.

Here is the documentation for all track commands.

## Conclusion

Once you get over the initial preparation, adding and manipulating tracks becomes a breeze and allows for a great amount of creative headroom. However, as I said before, this may not be the most ideal way/easiest way to do it but based on the research I've done and the lack of up-to-date tutorials, this was the easiest and most understandable method I could find/come up with. Hope this helps!

1. https://twinelab.net/harlowe-audio/#/
2. https://twinelab.net/harlowe-audio/#/v2
3. https://jukehost.co.uk/
4. https://twine2.neocities.org/#
5. https://www.youtube.com/watch?v=bm9Lvd1Qg4Y
6. https://twinelab.net/harlowe-audio/demo/