pcm-convert/readme.md

Convert pcm data from one format to another

# pcm-convert [![unstable](https://img.shields.io/badge/stability-unstable-green.svg)](http://github.com/badges/stability-badges) [![Build Status](https://img.shields.io/travis/audiojs/pcm-convert.svg)](https://travis-ci.org/audiojs/pcm-convert) [![Greenkeeper badge](https://badges.greenkeeper.io/audiojs/pcm-convert.svg)](https://greenkeeper.io/)

Convert data from one pcm-format to another.

## Usage

[![npm install pcm-convert](https://nodei.co/npm/pcm-convert.png?mini=true)](https://npmjs.org/package/pcm-convert/)

```js
const convert = require('pcm-convert')

//convert data from float32 to uint8 array
let uint8arr = convert([0, 0.1, 0.1, 0], 'float32', 'uint8')

//convert interleaved uint8 to planar float32 array
let float32arr = convert(new Uint8Array([127, 200, 127, 200]), 'uint8 stereo interleaved', 'float32 planar')

//deinterleave keeping the same data type
let int8arr = convert(new Int8Array([-100,100,-100,100]), 'interleaved', 'planar')

//change endianness keeping the same data type
let float32be = convert(new Float32Array([1,.5,-.5,-1]), 'le', 'be')

//use objects as formats
let float64 = convert(float32be, {
	dtype: 'float32',
	channels: 2,
	interleaved: false,
	endianness: 'be'
}, {
	dtype: 'float64',
	interleaved: true,
	endianness: 'le'
})

//skip source format string, convert directly to data format
let uint16 = convert(new Uint8Array([0,255]), 'uint16')

//put data into target container skipping format strings
convert(new Uint8Array([0,255]), new Uint16Array(2))

//full arguments case
let uint16arr = convert([0, 0, 1, 1], 'float32 le stereo planar', 'uint16 interleaved be', new Uint16Array(4))
```

## API

### convert(src, srcFormat?, dstFormat?, dst?)

Takes data in `src` container and converts from `srcFormat` to `dstFormat`. Format can be whether a string with tags or an object with properties, see [audio-format](https://github.com/audio-format) module. If `srcFormat` is skipped, it is detected from `src`. Optionally a destination container can be provided as `dst`, and in case if `dstFormat` is skipped, it will be detected from `dst`.

#### Source

Source format is inferred from `src` data type and extended with `srcFormat` properties. By default source is considered `planar mono le`. Source data types:

| Type | Dtype |
|---|---|
| `Array` | `float32` |
| `Float32Array` | `float32` |
| `Float64Array` | `float64` |
| `ArrayBuffer` | `uint8` |
| `Buffer` | `uint8` |
| `Uint8Array` | `uint8` |
| `Uint8ClampedArray` | `uint8` |
| `Uint16Array` | `uint16` |
| `Uint32Array` | `uint32` |
| `Int8Array` | `int8` |
| `Int16Array` | `int16` |
| `Int32Array` | `int32` |

#### Format

Can be defined as `dtype` string with tags, eg. `'uint8 interleaved mono le'`, `'float64 planar quad'` (some tags can be skipped), or an object with the following properties:

| Property | Meaning |
|---|---|
| `dtype` | Data type string: `uint8`, `uint16`, `uint32`, `int8`, `int16`, `int32`, `float32`, `float64`, `array` (only `dstFormat`), `arraybuffer` (only `dstFormat`).  |
| `interleaved` | Boolean indicating if data has `interleaved` or `planar` layout. |
| `channels` | Number of channels in source: `mono`, `stereo`, `quad`, `5.1`. |
| `endianness` | `be` or `le`, defaults to OS endianness. |



## Related

* [audio-format](https://github.com/audiojs/audio-format) - audio format notation parser/stringifier.
* [audio-speaker](https://github.com/audiojs/audio-speaker) - output data to speaker in node.
* [dtype](https://github.com/shama/dtype) - list of standard data types.

## License

© 2017 Dima Yv. MIT License