DEV Community: Wouter

How to use API keys in client-side Javascript

Wouter — Thu, 17 Sep 2020 14:47:51 +0000

Managing API keys in front-end codebases can be a little tricky, especially for people who aren't very experienced with it. Here's an introduction to API keys and an overview of what to do and what not to do when it comes to key management in client-side Javascript.

Types of API keys

Generally speaking, there are two types of API keys: secret keys and read-only keys. Sometimes these are called private or public API keys, but it's best to use different terms to avoid confusion with SSH keys.

Secret keys

These are your traditional API keys that have write access to the API resources. They can modify data, delete records, or even disable your entire account. If someone got a hold of these API keys, they could do a lot of damage. Depending on what functions the API allows, malicious use of your secret API key could cost you a lot of time and money.

Never ever use secret keys in client-side code.

No, I don't want to hear about your clever obfuscation that prevents people from lifting your key from your source code. Or any one of a dozen other ways you might have "hidden" your API key. If your client-side code makes an HTTP request with that key, it will show up in the network panel of the browser's developer tools for anyone to see.

Just don't put them in your code.

The docs for the Ghost Admin API explain that the API key is only suitable for server-side environments

Read-only keys

These API keys are specifically designed to be used in client-side code. They can only read data from the API, not write to it or change anything. So even if someone got a hold of a read-only API key, they couldn't do any damage to your data.

Whether an API can be used in client-side code is often noted explicitly in the documentation.

The docs for the updown.io API explain the read-only API key

How to add API keys to your bundle

If you're using a bundler, adding API keys or other configuration is usually fairly easy. The standard way in Node.js is to use dotenv to load a .env file and access the environment variables through process.env.*. Most Javascript bundlers support this as well, either built-in or through plugins.

Webpack: dotenv-webpack, or simply the built-in DefinePlugin
Rollup: @rollup/plugin-replace along with dotenv
Parcel: built-in

What about unbundled javascript files?

If you're not using a bundler, embedding configuration values an be a little trickier. My preferred solution is to create a config.json file and fetch() the config data in my Javascript file.

{
  "apiKey": "My read-only API key"
}

config.json

fetch('/config.json').then(function (config) {
    console.log('API key:', config.apiKey);
});

script.js

Simply add the config.json to your .gitignore and treat it the same as you would a .env file.

Of course, the downside of this method is that you have to make an additional network request. You can mitigate the delay by adding a <link rel="preload"> tag to your page, but it will still have some effect on how fast your Javascript will be ready to run.

Keeping that in mind, I highly recommend using a tool like Parcel to bundle your Javascript code. It will improve the load times of your web app and it will make your life easier.

However, if you're not working on a large online platform, if you're just writing some Javascript for your personal blog or website, then you have to ask yourself...

Do I need to hide my API keys?

The popular Twelve-Factor App principles state that configuration, such as credentials to external services (i.e. API keys), should be stored in the environment. This means using something like dotenv to load and manage your config, rather than including it directly in your code and pushing it to your repository. And I completely agree with that.

Complex front-end applications need bundlers, API key management, minification and other optimisations, and many more things that make the website better and faster.

However, most of the sites on the internet are not large platforms. They're personal websites, blogs, online playgrounds for people just discovering the joys of web development. If you're working on a site like that, chances are most of the aspects of the Twelve-Factor App don't even apply to you. So why should the rule about configuration?

As long as you're using read-only API keys, there is no risk in simply pasting your API key into your Javascript code where you need it. It will be published on your website anyways, so people who really want your API key will find it even if you manage not to put it in your Github repository. So if they can't do anything wrong with the key itself, there's nothing to worry about.

So go ahead and build that awesome site using a simple .html file and some .js files in a folder. Just remember to use the correct, read-only API keys.

Publishing a Rust binary on npm

Wouter — Mon, 16 Dec 2019 18:25:00 +0000

Instead of asking your users to install the entire Rust toolchain just to compile your program with cargo, it may be easier to let them install it through npm. Here's how to set it up.

I recently wrote a CLI tool in Rust, called Project Cleanup. I published it on crates.io, the Rust package manager, so people can install it with cargo install project-cleanup. Great! It's published! But this is a program that everyone could use, not just Rust developers, so I wanted to provide a way for non-Rust developers to install it.

These days I mostly write Javascript code so I use npm daily. Npm makes it very easy to install and update global packages, and publishing my Rust program worked surprisingly well. So here's a little guide on how to set it all up.

Step 0: Research

There are several good solutions to publish binaries to npm, but the most common is using pre-compiled binaries that are downloaded as-needed. The npm package will just be a tiny wrapper that downloads the appropriate binary when it's installed. A lot of native packages on npm use a this approach because it's easy to set up and maintain.

We'll be using a package called binary-install. It's built by a Rust developer and used for the npm package of wasm-pack, a popular tool to compile Rust programs to WebAssemly.

Step 1: Building the binaries

I implemented cross-compilation for Windows, Linux and Mac OS through Github Actions for Project Cleanup. You can check out the build workflow but for this post I'm going to focus mainly on the npm part.

File structure

The binary-install package requires your files to be in a specific structure:

Your release should be a .tar.gz archive
Inside that archive should be a directory, containing the binary
The archive filename and the directory name should be the same

So you should end up with something like this:

my-program-win64.tar.gz/my-program-win64/my-program.exe

This is somewhat of a convention to use when releasing binaries, especially on linux platforms. But it's good to note that binary-install expects exactly this structure.

Creating the files

The following is a simplified version of the build script I use. Adjust paths, filenames and targets where necessary to fit your program.

1. Compile the binary

First of all, we need to build our Rust program.

cargo build --release --target=x86_64-pc-windows-gnu

2. Create the directory structore

Next, create a new directory and copy the compiled binary into that directory. This is the directory that we'll put in our release archive.

It's best to use a separate directory outside of the target directory, because there are a lot of other files in there that don't need to end up in our release.

mkdir -p builds/my-program-win64

# If you haven't set a target, the path will just be 'target/release/...'
cp target/x86_64-pc-windows-gnu/release/my-program.exe builds/my-program-win64

3. Pack the archive

Now all we need to do is pack it all into a nice .tar.gz archive.

tar -C builds -czvf my-program-win64.tar.gz my-program-win64

You should have a file called my-program-win64.tar.gz now. Repeat as needed for every target you want to support.

Step 2: Creating a release

Once you have all your release archives, create a new release on Github. You can do this by creating a tag locally and pushing it to Github, or by creating a release via the web interface. Check out the Github documentation for more help.

Attach the .tar.gz files that you created to the release, write some release notes if you want, then click "Publish release" when you're ready.

Your binaries are ready! Now let's make an npm package that can install them.

Step 3: Making the npm package

I like to keep the npm package and the Rust project together in the same repository, but you can also create a separate project for the npm package if you prefer.

Create a new node project and add the binary-install dependency.

yarn init -y
yarn add binary-install

The example project in the binary-install repository is very clear and shows us what we need to do — although we're going to make a few tweaks.

Let's also create a new directory called npm to put our scripts.

mkdir npm

The Binary class

If we want to do anything, we first need to create an instance of the Binary class, provided by the binary-install package.

Get binary

Let's create a function that returns the proper Binary instance.

npm/getBinary.js

const { Binary } = require('binary-install');

function getBinary() {
    const version = require('../package.json').version;
    const url = `https://github.com/username/my-program/releases/download/v${ version }/my-program-win64.tar.gz`;
    const name = 'my-program';
    return new Binary(url, { name });
}

module.exports = getBinary;

We get the current version from the package.json file, so users can install a specific version of our program. This means that we have to keep our npm package's version synchronised with our release versions.

Don't forget to change the values in url and name.

Multiple platforms

Now you've probably spotted that this will always download the Windows binaries, even on non-Windows platforms. So let's do something about that. We can use the built-in Node.js module os to get information about the current platform.

npm/getBinary.js

const { Binary } = require('binary-install');
const os = require('os');

function getPlatform() {
    const type = os.type();
    const arch = os.arch();

    if (type === 'Windows_NT' && arch === 'x64') return 'win64';
    if (type === 'Windows_NT') return 'win32';
    if (type === 'Linux' && arch === 'x64') return 'linux';
    if (type === 'Darwin' && arch === 'x64') return 'macos';

    throw new Error(`Unsupported platform: ${type} ${arch}`);
}

function getBinary() {
    const platform = getPlatform();
    const version = require('../package.json').version;
    const url = `https://github.com/username/my-program/releases/download/v${ version }/my-program-${ platform }.tar.gz`;
    const name = 'my-program';
    return new Binary(url, { name });
}

module.exports = getBinary;

That should do the trick. This function will return the proper Binary instance for each supported platform. If you have different platform support, or different filenames, you can adjust the values and checks in the getPlatform() function.

Scripts

With our Binary instance, we can do 3 things: install, uninstall and run. So let's create a script for each of those.

npm/run.js

const getBinary = require('./getBinary');
getBinary().run();

npm/install.js

const getBinary = require('./getBinary');
getBinary().install();

npm/uninstall.js

const getBinary = require('./getBinary');
getBinary().uninstall();

It may seem a little excessive to create a separate file for each function, but it's the easiest way to call them from a script in package.json.

Update package.json

Now that we have the js files for these commands, we'll need to call them from our package.json. We'll install the binary with the postinstall hook.

package.json

{
  "scripts": {
    "postinstall": "node npm/install.js"
  }
}

Next, if our program is already installed and the user installs a new version, we should uninstall the old version first. Let's use the preinstall hook for that.

package.json

{
  "scripts": {
    "postinstall": "node npm/install.js",
    "preinstall": "node npm/uninstall.js"
  }
}

Once installed, we want the user to be able to run my-program from anywhere. Luckily, npm supports a bin field in package.json. We just need to point it to a script.

package.json

{
  "bin": {
    "my-program": "./npm/run.js"
  },
  "scripts": {
    "postinstall": "node ./npm/install.js",
    "preinstall": "node ./npm/uninstall.js"
  }
}

We also need to let the system know that this is an executable script, and to run it with node. We do this by adding a shebang to the top of the file.

npm/run.js

#!/usr/bin/env node

const getBinary = require('./getBinary');
getBinary().run();

Shebangs are a Unix concept, but npm will take care of the Windows side for us.

First install problem

We're almost done, but there's one more thing. I only learned this after releasing the my npm package, because it's not exactly obvious if you've followed these steps in order.

When installing locally, the preinstall script is executed before any dependencies are installed. But our script require()s a dependency. You can probably see where this is going — another developer who clones the repository and runs yarn install will get an error that dependencies are missing, and they'll be unable to install those dependencies.

We'll solve this with a simple try/catch and swallow the error. After all, if the dependencies are not found it means the package wasn't installed yet, and that means there's no binary to uninstall in the first place.

npm/uninstall.js

function getBinary() {
    try {
        const getBinary = require('./getBinary');
        return getBinary();
    } catch (err) { }
}

const binary = getBinary();
if (binary) {
    binary.uninstall();
}

Step 4: Publishing

Now our package is ready to publish. But let's make sure we only publish what's necessary for the npm package to work. We can use the files property in package.json to define which files get uploaded to npm. The package.json itself is always included, so we just need to add our scripts in the npm directory.

package.json

{
  "files": [
    "npm/**/*"
  ]
}

And that's it. Let's publish!

npm publish

Self-documenting is a myth, and how to make your code self-documenting

Wouter — Sat, 03 Aug 2019 00:00:00 +0000

Self-documenting code is often presented as a programmer's utopia, where you don't need to write comments at all! But code can never be entirely self-documenting. Here are some tips on how to clean up your code and write fewer comments without losing sight of the big picture.

What is self-documenting code

In order to write code, you have to understand the surrounding code. And in order to understand it, you need to read it. Often repeatedly and frequently. So it's in everyone's best interest that this code is clear, concise and properly documented.

Self-documenting code is a goal that a lot of developers (including myself) set for themselves at least once. For most people it means you should write clean, well-structured code that makes it immediately obvious what's going on, so you don't need to write comments explaining it.

Well actually...

You can write the best, cleanest, most well-structured code anyone has ever seen, but here's the truth: You'll still need to write comments and document your code. You won't have to write as many comments, but you can't stop writing comments altogether.

Three questions

When someone reads what you wrote, for them to build the mental modal they need to understand it, your code needs to answer three questions:

What is the goal of this code?
How is it achieving that goal?
Why does it achieve that goal in this way?

Let's take a little piece of less-than-ideal code, examine why it's written like that, and try to improve it so it answers all three questions.

Note: The code samples are written in Javascript/Typescript, but the theory should be applicable for any language

The code

While experimenting with a new feature, you're just trying to get something working. So it can be tempting to think "I'll clean this up later" and write something like this:

function get() {
    const arr = db.getAll();
    return arr.map(i => i.name);
}

Only you don't clean it up because deadlines are looming and you have ten more things to finish before tomorrow's standup. And so that piece of code sits in your codebase for seven months, until another developer — let's call him Steve — needs to update something in that file.

After reading the function for the first time, Steve will probably have several questions:

What is this function getting?
What is in arr?
Why does it map to name?

By parsing what's happening, Steve can deduce a partial answer to these questions:

The variable arr must be an array, given its name and the fact that arr.map() is used.
The values in arr must have a property called name since it is mapped.
The function returns an array.

As you can see, Steve is trying to deduce the what and the why based on the only thing he has: the how. This happens a lot, in all types of codebases, and most developers don't even think twice about it. But in the end, the time and energy you spent parsing this kind of code adds up and takes away from your time working on the code.

So how can we make it easier on Steve, so he can understand what's going on at a single glance?

Add comments

One solution would be to add some comments to explain what's going on.

/**
* Gets the names of all participants from the database
*/
function get() {
    // Load the participants from the database
    const arr = db.getAll();

    // Map to get just the participant's names
    return arr.map(i => i.name);
}

It has gotten a little clearer already, but adding comments is exactly what we wanted to avoid with our self-documenting code.

Name those variables

Instead of adding comments, how about we change the names of the variables to reflect what they mean?

function getParticipantNames() {
    const participants = database.getAllParticipants();
    return participants.map(p => p.name);
}

Now we have communicated essentially the same thing as before, but we didn't need all those comments. Properly naming your variables is one of the cornerstones of self-documenting code, because they communicate exactly what they represent.

Note how I still used a short variable p in the participants.map() function, since it's abundantly clear from the context that it will contain the participant.

So with these changes to the variable names, we've answered our original questions:

What is this function getting? It gets the names of the participants.
What is in arr? The participant entities.
Why does it map to name? Because we only need the name

Steve will find it much easier next time he has to read our code!

Why?

Another question you could ask is a little more far-fetched and doesn't concern this function specifically, but I'll ask it anyway: Why is there no function called database.getAllParticipantNames(), to query just the names from the database (instead of all this other data we don't need)?

There could be a million different technical reasons for this, but for this example let's say that the database queries are cached. This means that when the query runs, the received data is stored in memory for a little while so subsequent calls don't need to make another roundtrip to the database. So using the same query here is actually an optimisation, even if we get too much data from the call.

This optimisation is an example of something you can't possibly communicate using code alone. As it turns out, purely "self-documenting" code is simply insufficient to paint the whole picture. So we will need some comments after all.

function getParticipantNames() {
    // Because queries are cached, using the `allParticipants` query 
    // prevents another roundtrip to the database
    const participants = database.getAllParticipants();

    return participants.map(p => p.name);
}

With this, we've made the Why even more complete. We needed comments to fully document the code, but this code can still be considered "self-documenting".

What?

There is one last question remaining, one asked not by Steve who has to look at your function, but rather by Tom who has to use it in another part of the codebase: What is the return type of this function?

The best solution for that is type annotations. Statically typed languages like Java, C# or Rust don't need any additional work since they require explicit type information to work. But dynamically typed languages like Javascript and Python don't have this luxury. Luckily, most of these dynamically typed languages have solutions for (optional) typing. Javascript even has several — I've worked with JSDoc comments, Flow types and Typescript.

We've already tried the full JSDoc comment above, but all that's necessary to annotate the return type is an @returns statement in the comment:

/**
* @returns {string[]}
*/
function getParticipantNames() {
    // Because queries are cached, using the `allParticipants` query 
    // prevents another roundtrip to the database
    const participants = database.getAllParticipants();

    return participants.map(p => p.name);
}

Typescript and Flowtype use syntactic notations rather than comments. Note the : string[] after the function name:

function getParticipantNames() : string[] {
    // Because queries are cached, using the `allParticipants` query 
    // prevents another roundtrip to the database
    const participants = db.getAllParticipants();

    return participants.map(p => p.name);
}

My personal favourite is Typescript. It helps you create clean code with strict interfaces and it makes refactoring a whole lot easier when you need to. I use Typescript in nearly all of my projects.

However, it's important to note that adding Typescript to a project is generally not a decision to take lightly — especially if you have an already developed codebase — so be sure to consider the ramifications before you start. JSDoc is almost always the easiest choice to get started typing your code because it's based on comment blocks, which have no impact on the code itself.

Conclusion

Let's extract the three most important rules from what we've seen in this post, based on the three questions:

Use clear and consistent naming, types and function signatures to communicate what the goal of each piece of code is.
Use well-structured code to show how you're going about achieving the goal.
Use comments to explain why you're doing things a certain way, especially if that way may be non-obvious.

That last one is the hardest for a lot of developers because the why is usually obvious while you're writing the code. But take a moment to think of the developers who will need to look at your code months or even years after you wrote it. They'll be grateful.

Make Steve happy. Document your self-documenting code.

Choosing a static site generator

Wouter — Sun, 28 Jul 2019 00:00:00 +0000

When I started building my blog, I knew from the start that I wanted to use a static site generator with markdown files. But I had no idea which SSG I should use. I've heard about them, and I know they've gained in popularity in the past couple of years, but until now when I made a static site it was just a folder of HTML files. But now I decided to do it properly, since I was going to build a whole new blog. So I started searching.

After a few Google searches, I found a website called StaticGen.com which lists a lot of static site generators (I didn't even know there were that many!). The site also provides filters to search for exactly the type of SSG you want. Of course, since I was new at all this, I had no idea what I needed from a static site generator, so I started with the top entries on the list.

I'm going to list good and bad things about each of the tools I tried. These are just my initial experiences based on working with them for a short time. Your mileage may vary.

Jekyll

The 'classic' static site generator, Jekyll has been around for ages, it's stable and boring. A great choice for a writer or someone who just needs their site online. A little less fun for someone who wants to use their site as a personal playground for experimenting (like me).

I liked

Stable, battle-tested and production-ready
Can deploy directly to Github pages
Big community, lots of info to be found and most problems have been solved before

I didn't like

Liquid templates have limited logic (also I'm not a fan of the {% %} syntax)
It requires Ruby, GCC and Make, which are a bit of a headache to set up

In the end, I didn't go with Jekyll because of its limited support for custom logic or functionality.

Hugo

Next on the list is Hugo. This one is built in Go, another language and toolset that I don't use, but is downloadable as a simple binary.

I liked

It's fast, especially compared to Javascript-based alternatives
Their system of page resources, while not always properly documented, works very nicely and intuitively
Resource pipes with transform functions are implemented very nicely
You can download a binary instead of compiling Hugo from source

I didn't like

I found the template syntax to be just awful if you want to do anything beyond printing variables and simple if-statements

Unfortunately, that one dislike was a dealbreaker for me. If it wasn't for the clumsy and messy templates, I probably would've stuck with Hugo. But the way I had to interpolate variables, the function calls without parentheses, and the fact that the template compiler doesn't support line breaks in code blocks, made for the worst code mess I've ever seen.

A short example of what this means:

{{ $css := resources.Get "css/pageStyles/post.scss" | resources.ExecuteAsTemplate (printf "page-%s.scss" .File.UniqueID) .Params.colour | resources.ToCSS (dict "outputStyle" "compressed") }}

This line gets an SCSS file, fills the template tags inside it with a variable, and then renders it to CSS. On their own, these functions aren't that bad. But put together in this way the whole thing becomes difficult to visually grok what's going on and impossible to debug or change without a lot of trial-and-error.

Now I'm sure there must be good reasons why the template syntax is like this, but there were so many little annoyances and inconveniences that I simply gave up after building about two-thirds of the blog in Hugo.

Gatsby

The next step on my search was Gatsby. As a front-end developer first and foremost, the concept of using React — a front-end framework — to build a front-end website, sounded logical. Next to the pre-rendered static HTML, Gatsby outputs a React-powered bundle of Javascript to turn the rest of the site into a progressive web app (PWA for short). This makes for a fast initial load time because of the static HTML, and then even faster navigation due to the powers of the PWA.

I liked

Static sites for front-end developers
Generates static HTML pages for SEO, and then hydrates those pages with the client-side Javascript bundle

I didn't like

I'm not a big fan of React

In any case, I like the concept of Gatsby, but I'm more partial to Vue and I have a lot more experience with it, so I decided to look for something similar in Vue-land.

Gridsome

Gridsome is essentially the same as Gatsby, but it replaces React with Vue.js, which is pretty much exactly what I was looking for at this point.

I checked out some other Vue-based alternatives, specifically Nuxt.js (aimed at server-rendered applications) and Vuepress (for documentation sites), but Gridsome seemed the most geared towards building a static blog.

I liked

Everything good about Gatsby, but with Vue instead of React.

I didn't like

It's relatively new and hasn't got a large community behind it yet, so finding answers to specific questions can be a little difficult.

Gridsome is pretty early in development and is still finding itself, but I found the latest version at this time (v0.6.7) to be sufficiently stable. They've got some serious work to do before it could be considered production-ready — I especially found error-handling to be lacking during my initial tests — but overall it has worked well for me. Gridsome has allowed me to use my Vue experience to build a nice looking blog with relatively little effort.

Side note: GraphQL

Like Gatsby, Gridsome uses GraphQL to describe which page data to load. I've seen GraphQL get a lot of praise from developers online, but I hadn't actually worked with it until now. The ideas behind GraphQL sound very good and I could definitely see it work, but my practical experience is that the queries often feel a little bloated and excessively verbose at times. On my post details page, I just want all the properties from my Post type, why do I need to write them out manually?

I also haven't figured out sorting and filtering yet, so I've got some learning to do still. But by looking at the Gridsome starters and examples I've managed to get my blog up and running.

Conclusion

All static site generators have pros and cons, and I can't recommend enough that you just try them all out for a few hours to see how they work. Most of the time you'll figure out very quickly if the tool's workflow matches yours or not, and then you can move on to the next one.

The best resource I found to search for SSGs is StaticGen.com. If you're trying to find a good static site generator, this is the best place to start your search. Not every tool is for everyone, but there's bound to be one that works just right.

In any case, so far I'm very happy with my choice of Gridsome. I plan to do a write-up later about my experience building a site with it, but I decided to keep this post just about the selection process.

Making a background music player in Godot

Wouter — Sat, 27 Apr 2019 00:00:00 +0000

This is my first blog post. If you notice anything out of the ordinary (styling, structure, content, anything), let me know so I can fix it and learn for my next posts!

There are multiple ways to play and manage music tracks for your game but most are linked to your scene. In this tutorial we'll make an autoload music manager that will allow to you play background music independent from your game scenes.

What we need

Godot 3.1

You can use another version of Godot, but this tutorial is written with Godot 3.1.

Download Godot at godotengine.org

Music

Since we're making a music player, you'll need two music tracks. Godot supports .wav and .ogg formats, but they recommend using .ogg for background music because it takes up a lot less disk space than .wav.

If you don't have music, you can find some nice free tracks at incompetech.

Autoload

We're going to use the autoload feature in Godot. This lets us add static nodes to the scene tree that will always exist, independent of our game scenes.

This is perfect to keep our music playing, even if we change the scene.

If you want to learn more about autoload you can check out the Godot docs.

Getting Started

Our project will consist of 3 scenes: Scene1 and Scene2 will be our regular game scenes, and we'll add some buttons to them to manage the music.

MusicController will be our special autoload scene. We'll add some custom functions to this scene so that we can easily play our music from anywhere in our game.

Scene 1

Create a new scene and call it Scene1. Then add 1 label and 3 buttons as in the screenshot below.

Add a script to the root node of the scene, and connect the pressed() events of the three buttons to it.

# Scene1.gd

extends Control

func _on_GoToScene2Button_pressed():
    get_tree().change_scene("res://Scene2.tscn")

func _on_PlayTrack1Button_pressed():
    pass # Replace with function body.

func _on_StopMusicButton_pressed():
    pass # Replace with function body.

Scene 2

Now make another scene and call it Scene2. Add 1 label and 2 buttons.

Next, add a script to the root node of the scene and connect the pressed() events of both buttons to it.

# Scene2.gd

extends Control

func _on_GoToScene1Button_pressed():
    get_tree().change_scene("res://Scene1.tscn")

func _on_PlayTrack2Button_pressed():
    pass # Replace with function body.

Music Controller

Now it's time to create our music controller scene.

Create a new scene and call it MusicController. Add 1 AudioStreamPlayer to play our music.

Add a script to the root node of the scene and add the following code to it:

# MusicController.gd

extends Control

# Load the music player node
onready var _player = $AudioStreamPlayer

# Calling this function will load the given track, and play it
func play(track_url : String):
    pass

# Calling this function will stop the music
func stop():
    pass

As you see, we have defined 2 functions: play() and stop(). We'll be using these to play and stop the music as needed from our game scenes.

Side note: wondering what that track_url : String syntax is? It's a new feature in Godot 3.1 called optional typing. It means we expect that function parameter to be a string, and the editor should warn us if we call that function with anything that isn't a string.

Stop()

Let's begin with the easiest function to implement. The stop() function simply needs to stop the music - hence its name.

Checking the documentation, we can see that AudioStreamPlayer has a stop() method, so all we need to do is call that method.

func stop():
    _player.stop()

Play()

This one is a little more involved. When the play() function is called, we need to do 3 things:

Stop the previous track
Load the new track from the track_url function parameter
Start playing the new track.

Luckily, it's not difficult to do any of these things with GDScript.

Stop

To stop, the previous track, we simply call our own stop() method.

stop()

Load

Next, we need to load the new track. GDScript makes this very easy with the load() function.

var new_track = load(track_url)

Update

Now we have to update the player and tell it to use the track we just loaded.

Returning to the documentation, we can see that AudioStreamPlayer has a property stream that we can set.

_player.stream = new_track

Play

Now all we have to do is start the track.

_player.play()

Everything together

Our MusicController script looks like this now:

# MusicController.gd

extends Control

# Load the music player node
onready var _player = $AudioStreamPlayer

# Calling this function will load the given track, and play it
func play(track_url : String):
    var track = load(track_url)
    _player.stream = track
    _player.play()

# Calling this function will stop the music
func stop():
    _player.stop()

Set Up Autoload

The last thing we need to do is tell Godot to actually load our autoload scene.

Go to the Project menu and open Project Settings. Then click on the AutoLoad tab. This is where we can configure our autoload scripts.

An autoload script always has a path that points to the resource (either a script or a scene) that should be loaded, and a name that you can use to refer to it in your code.

Side note: You can also access autoload nodes through the scene tree. See the autoload documentation for more information.

To add our MusicController scene to the autoload settings, select it in the Path field. You can look for it with a file browser by clicking the little button next to the field.

The Node name should automatically get filled based on the name of the scene. You can change this if you want, but we'll leave it for now.

Click the Add button to add the autoload scene to the project. It will appear in the list below.

Every autoload script has some buttons that allow you to edit or remove the autoload script, and to change the order in which they are loaded. They also have an enabled checkbox so you can temporarily disable an autoload script without having to delete it and re-add it if you want to test something.

Make sure enabled is checked for our new MusicController autoload script.

And that's it! Our autoload scene has been added and is now active in the project! This means we can access the play() and stop() functions we made through the global MusicController variable. So let's try that out.

Using Your Autoload Functions

In the Scene1 and Scene2 scripts, we can now call the functions we need in the pressed events. The scripts will look something like this:

# Scene1.gd

extends Control

# Switch to the other scene
func _on_GoToScene2Button_pressed():
    get_tree().change_scene("res://Scene2.tscn")

# Load and play track 1
func _on_PlayTrack1Button_pressed():
    MusicController.play("res://tracks/track 1.ogg")

# Stop the music
func _on_StopMusicButton_pressed():
    MusicController.stop()

# Scene2.gd

extends Control

# Switch to the other scene
func _on_GoToScene1Button_pressed():
    get_tree().change_scene("res://Scene1.tscn")

# Load and play track 2
func _on_PlayTrack2Button_pressed():
    MusicController.play("res://tracks/track 2.ogg")

Don't forget to set the correct paths to your tracks.

Done

Now we can run the game and enjoy the music. Notice how it doesn't stop playing, even if you change to the other scene!

That's what autoload is all about.