Skip to content

Commit

Permalink
applying formatter and fixing links
Browse files Browse the repository at this point in the history
  • Loading branch information
Lusito committed Jun 1, 2024
1 parent e873417 commit c26141f
Show file tree
Hide file tree
Showing 7 changed files with 32 additions and 28 deletions.
22 changes: 11 additions & 11 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
name: Documentation
on:
push:
branches: [ master ]
branches: [master]
jobs:
build:
name: Documentation
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- name: Install
run: npm ci
- name: Build Docs
run: npm run build:docs
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist-internal/docs
- uses: actions/checkout@master
- name: Install
run: npm ci
- name: Build Docs
run: npm run build:docs
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist-internal/docs
16 changes: 10 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,28 +11,30 @@ It has been written to simplify playing sounds in games.
It is not meant as a fully-fledged audio library.

**Features:**

- Playing sounds with and without position and orientation (positional-audio / spatialization)
- A SoundSource (position + orientation) can play multiple sounds
- You can play sounds on channels (if the specified channel already plays a sound, it will be stopped)
- Sounds can of course be played freely (not on a channel)
- It does not abstract away the web audio API. It only simplifies its usage. So you can still use the full power of the web audio API.

**What it doesn't do:**

- Preloading sounds (that's up to you or a different asset manager)
- Manipulating sounds
- Fallback if web audio API is not supported

If you are looking for a more complete solution, you might want to take a look at [howler](https://www.npmjs.com/package/howler).


#### Fair Warning

The compile target of this library is es2015, so if you want to support older browsers, you'll have to ensure that this module is being transpiled to an older es version during your build-process.

### Get started

* [Read the documentation](https://lusito.github.io/sounts/)
* Look at the example (`example/*.ts`).
* Ask questions if the above doesn't clarify something good enough.
- [Read the documentation](https://lusito.github.io/sounts/)
- Look at the example (`example/*.ts`).
- Ask questions if the above doesn't clarify something good enough.

## Goals of this Project

Expand All @@ -45,23 +47,25 @@ While looking at existing libraries, I mostly found packages, that have not been
The only library I deemed worthy of considering was [howler](https://www.npmjs.com/package/howler). It's actively maintained, has type definitions via `@types/howler` and `0` dependencies.

But two aspects remained (If those don't concern you, you should consider howler):

- It's big: [9.5kB minified + gzipped](https://bundlephobia.com/package/howler).
- And it abstracts a lot of the web audio part away.

### Working with Raw Web Audio API

After that, I took a look at web audio API tutorials, most of which have been written almost a decade ago. Here are the top 3:

- [Getting Started with Web Audio API](https://www.html5rocks.com/en/tutorials/webaudio/intro/)
- [Developing Game Audio with the Web Audio API](https://www.html5rocks.com/en/tutorials/webaudio/games/)
- [Web audio spatialization basics](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics)

That's a lot to read and a lot to adjust for, as the API has changed a bit since then. Even JavaScript has changed quite a lot since then.
That's a lot to read and a lot to adjust for, as the API has changed a bit since then. Even JavaScript has changed quite a lot since then.

Those tutorials are still worth a read, at least for the theory. You'll have to adjust the code a bit to work with the current standard.

### Deciding to Write Something New

So, here I am again starting the same old thought: "*There has to be a better way...*" (... to get started with web audio).
So, here I am again starting the same old thought: "_There has to be a better way..._" (... to get started with web audio).

The goal of this library is to have a simple starting point for writing positional audio code with the web audio API without having to dig into old tutorials and convert all the legacy code examples to the new standard.

Expand Down
2 changes: 1 addition & 1 deletion docs/channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Channels are a way of avoiding to play conflicting sounds.

Imagine you have an announcer (someone that gives you information) and you let it play a message to the user. Now, for some reason, another message is being played to the user. He will have to listen to two talkers at the same time, which is not something you can expect of your users.

To solve this issue, both [SoundPlayer](../api/classes/SoundPlayer.md) and [SoundSource](../api/classes/SoundSource.md) (which extends SoundPlayer) allow you to play sounds on channels (by name).
To solve this issue, both [SoundPlayer](https://lusito.github.io/sounts/api/classes/SoundPlayer.html) and [SoundSource](https://lusito.github.io/sounts/api/classes/SoundSource.html) (which extends SoundPlayer) allow you to play sounds on channels (by name).

If a sound is already being played on a channel, it will be stopped before playing the new one.

Expand Down
4 changes: 2 additions & 2 deletions docs/gain.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Once you add positional audio, it might look like this:
(AudioBufferSourceNode -> PannerNode) -> AudioContext.destination
```

The brackets represent the nodes within the [SoundSource](../api/classes/SoundSource.md), so you have one context, but multiple PannerNodes connected to this context.
The brackets represent the nodes within the [SoundSource](https://lusito.github.io/sounts/api/classes/SoundSource.html), so you have one context, but multiple PannerNodes connected to this context.

Now, in order to control the global "volume", we need to insert a GainNode right before the AudioContext:

Expand Down Expand Up @@ -73,7 +73,7 @@ const source = new SoundSource(mainVolume, { gain: 0.75 });
source.setGain(0.5);
```

By passing in a gain value as option to the [SoundSource](../api/classes/SoundSource.md) constructor, a gain node will automatically be added to the source.
By passing in a gain value as option to the [SoundSource](https://lusito.github.io/sounts/api/classes/SoundSource.html) constructor, a gain node will automatically be added to the source.

**Note**, that you can't call setGain unless you passed a gain value in the options parameter.

Expand Down
4 changes: 2 additions & 2 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ async function init() {

## Create a SoundPlayer and Play a Sound

The easiest way to play (non-positional) sounds is using the [SoundPlayer](../api/classes/SoundPlayer.md) class:
The easiest way to play (non-positional) sounds is using the [SoundPlayer](https://lusito.github.io/sounts/api/classes/SoundPlayer.html) class:

```typescript
import { SoundPlayer } from "sounts";
Expand All @@ -54,7 +54,7 @@ You want to add position, volume and more to your sounds? Check out the other tu

## Stop a Sound

The `play()` method of [SoundPlayer](../api/classes/SoundPlayer.md) returns an `AudioBufferSourceNode`, which you can use to stop the sound:
The `play()` method of [SoundPlayer](https://lusito.github.io/sounts/api/classes/SoundPlayer.html) returns an `AudioBufferSourceNode`, which you can use to stop the sound:

```typescript
const sourceNode = player.play(audioBuffer);
Expand Down
8 changes: 4 additions & 4 deletions docs/positional-sound.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ With **sounts** this is easily done:

This is an optional step if you want to change the position and orientation of the listener. Think of the listener as the camera of the audio world.

If you don't set up a [SoundListener](../api/classes/SoundListener.md), it will be located at (0, 0, 0) with a forward vector of (0, 0, -1) and an up vector of (0, 1, 0).
If you don't set up a [SoundListener](https://lusito.github.io/sounts/api/classes/SoundListener.html), it will be located at (0, 0, 0) with a forward vector of (0, 0, -1) and an up vector of (0, 1, 0).

```typescript
import { createSoundListener } from "sounts";
Expand All @@ -30,7 +30,7 @@ If you are wondering why you'd want to use createSoundListener rather than modif
## Create a SoundSource

Now that you have your listener configured, you want to play sounds in the 2D/3D world.
A [SoundSource](../api/classes/SoundSource.md) extends the [SoundPlayer](../api/classes/SoundPlayer.md) with a position, orientation and other options related to positional audio.
A [SoundSource](https://lusito.github.io/sounts/api/classes/SoundSource.html) extends the [SoundPlayer](https://lusito.github.io/sounts/api/classes/SoundPlayer.html) with a position, orientation and other options related to positional audio.

```typescript
import { SoundSource } from "sounts";
Expand All @@ -44,14 +44,14 @@ const audioBuffer = ...;
source.play(audioBuffer);
```

As you can see, it's really simple to work with a [SoundSource](../api/classes/SoundSource.md). Check out the API documentation to see what other options you have.
As you can see, it's really simple to work with a [SoundSource](https://lusito.github.io/sounts/api/classes/SoundSource.html). Check out the API documentation to see what other options you have.

## Orienting a SoundSource

When creating a sound source, you have the option of configuring a cone.
Check out the [documentation at MDN](https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/coneInnerAngle) to learn more about the cone.

If you specify a cone for the [SoundSource](../api/classes/SoundSource.md), you can also set its orientation:
If you specify a cone for the [SoundSource](https://lusito.github.io/sounts/api/classes/SoundSource.html), you can also set its orientation:

```typescript
import { SoundSource } from "sounts";
Expand Down
4 changes: 2 additions & 2 deletions mono-docs.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
siteName: 'sounts'
title: ''
siteName: "sounts"
title: ""
description: A tiny helper library for working with the web audio API written in TypeScript.
footer:
- Zlib/Libpng License | https://github.com/Lusito/sounts/blob/master/LICENSE
Expand Down

0 comments on commit c26141f

Please sign in to comment.