---
title: Files and editing
order: 1
summary: Create, load, save and edit audio buffers.
---

<!-- Generated by tools/generate-docs.bxs from the BIF classes. Do not edit; change the Javadoc and run it again. -->

Create, load, save and edit audio buffers.

## audioSilence

Creates an audio buffer filled with silence. Useful as a blank canvas to mix sounds into.

```js
audioSilence( seconds, channels=2, sampleRate=44100 )
```

| Argument | Type | Default | |
|---|---|---|---|
| `seconds` | double | required | The length in seconds, rounded to the nearest frame. |
| `channels` | integer | `2` | The number of channels, 1 for mono, 2 for stereo. Defaults to 2. |
| `sampleRate` | integer | `44100` | The sample rate in Hz. Defaults to 44100. |

**Returns** The new audio buffer.

## audioLoad

Reads an audio file fully into memory. WAV (PCM at 8, 16, 24 and 32 bits, and IEEE float) and MP3 are supported, and the format is found from the content of the file, not its name. MP3 needs the optional codec jars that ship with the module.

```js
audioLoad( path )
```

| Argument | Type | Default | |
|---|---|---|---|
| `path` | string | required | The path of the audio file. Relative paths and mappings are resolved like other file functions. |

**Returns** The audio buffer.

## audioSave

Writes an audio buffer to a file, replacing any existing file. Missing parent folders are created. The format follows the file extension: .wav (or none) writes WAV and .mp3 writes a constant bitrate MP3, which needs the optional codec jars that ship with the module. Any other extension is an error.

```js
audioSave( audio, path, bitDepth=16, bitrate=0 )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer to save. |
| `path` | string | required | The destination path. Relative paths and mappings are resolved like other file functions. |
| `bitDepth` | integer | `16` | For WAV: 16 or 24 for integer PCM, or 32 for 32 bit float. Defaults to 16. Samples beyond -1 to 1 are clipped for 16 and 24. Ignored for MP3. |
| `bitrate` | integer | `0` | For MP3: the constant bitrate in kbps. At 32, 44.1 and 48 kHz use 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320. At lower sample rates use 8 to 160 (8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160). Defaults to 0, which means 192, or 128 below 32 kHz where 192 does not exist. Ignored for WAV. |

**Returns** The absolute path of the file that was written.

## audioInfo

Describes some audio. A WAV file is described from its header, so a file of any size answers at once; the other formats are decoded. The peak and rms of a file are measured, which reads all of it, only when levels is true. A buffer always has them.

```js
audioInfo( source, levels=false )
```

| Argument | Type | Default | |
|---|---|---|---|
| `source` | any | required | An audio buffer, or the path of an audio file. |
| `levels` | boolean | `false` | Measure peak and rms of a file too. Reads the whole file. |

**Returns** A struct with channels, sampleRate, frames and seconds, and peak (0 to 1 for undistorted audio) and rms when they were measured.

## audioWaveform

Summarize audio as a list of peak levels for drawing a waveform. The audio is split into equal slices and each value is the loudest absolute sample in its slice across all channels.

```js
audioWaveform( audio, points=800 )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. |
| `points` | integer | `800` | How many values to return, from 1 to 100000. Defaults to 800. |

**Returns** An array of numbers from 0 (silence) upwards, 1 is full scale.

## audioGain

Change the volume of an audio buffer. The input buffer is left untouched.

```js
audioGain( audio, gainDb )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. |
| `gainDb` | double | required | The gain in decibels. Negative values make it quieter, 6 roughly doubles the amplitude. |

**Returns** A new audio buffer.

## audioPan

Position an audio buffer in the stereo field. The input buffer is left untouched.

```js
audioPan( audio, pan )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | A mono or stereo audio buffer. Mono becomes stereo, stereo is treated as a balance control. |
| `pan` | double | required | From -1 for hard left through 0 for center to 1 for hard right, using a constant power law. |

**Returns** A new audio buffer.

## audioFade

Fade an audio buffer in and out. The input buffer is left untouched.

```js
audioFade( audio, fadeIn=0, fadeOut=0, curve="linear" )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. |
| `fadeIn` | double | `0` | Length of the fade in, in seconds. Defaults to 0. |
| `fadeOut` | double | `0` | Length of the fade out, in seconds. Defaults to 0. |
| `curve` | string | `"linear"` | The fade shape: linear (default) or smooth, a raised cosine. |

**Returns** A new audio buffer.

## audioNormalize

Scale an audio buffer so its peak hits a target level. The input buffer is left untouched.

```js
audioNormalize( audio, targetDb=-1 )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. Silence is returned unchanged. |
| `targetDb` | double | `-1` | The target peak in decibels relative to full scale. Defaults to -1. |

**Returns** A new audio buffer.

## audioTrim

Cut a section out of an audio buffer. The input buffer is left untouched.

```js
audioTrim( audio, start=0, end )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. |
| `start` | double | `0` | Where the section starts, in seconds. Defaults to 0. |
| `end` | double | optional | Where the section ends, in seconds. Defaults to the end of the audio. Values past the end are clamped. |

**Returns** A new audio buffer.

## audioConcat

Join audio buffers end to end. The input buffer is left untouched.

```js
audioConcat( audios )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audios` | array | required | An array of audio buffers. They must share channel count and sample rate. |

**Returns** A new audio buffer.

## audioReverse

Reverse an audio buffer. The input buffer is left untouched.

```js
audioReverse( audio )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. |

**Returns** A new audio buffer.

## audioMix

Add audio buffers together so they play at the same time

```js
audioMix( audios )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audios` | array | required | An array of audio buffers. They must share channel count and sample rate. All start at time 0, the result is as long as the longest. |

**Returns** A new audio buffer. Scale it with audioGain() or audioNormalize() if the sum is too loud.

## audioChannels

Convert an audio buffer between mono and stereo. The input buffer is left untouched.

```js
audioChannels( audio, channels )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. |
| `channels` | integer | required | The target channel count. Mono to any count copies the signal, any count to mono averages the channels. |

**Returns** A new audio buffer.

## audioResample

Change the sample rate of an audio buffer. The input buffer is left untouched.

```js
audioResample( audio, sampleRate )
```

| Argument | Type | Default | |
|---|---|---|---|
| `audio` | any | required | The audio buffer. |
| `sampleRate` | integer | required | The new sample rate in Hz, using a windowed sinc filter. |

**Returns** A new audio buffer.