audiox

A TypeScript-based audio processing library & CLI that wraps ffmpeg, helping you optimize audio files in Node.js/Bun environments.

Features

• Audio optimizations and conversions
• Stream-based processing support
• Metadata handling
• Multiple output formats (WAV, MP3, AAC)
• Configurable audio properties (bitrate, channels, sample rate)
• Error handling and detailed logging
• Fully typed with TypeScript

Install

bun install @stacksjs/audiox

Get Started

There are two ways of using this tool: as a library or as a CLI.

Library Usage

Given the npm package is installed:

import { audio, audioInfo } from '@stacksjs/audiox'

// Basic audio conversion
await audio('input.mp3', 'output.wav', {
  codec: 'pcm_s16le',
  channels: 1,
  sampleRate: 16000,
  bitrate: '160k',
})

// Get audio file information
const info = await audioInfo('audio.mp3')
console.log(info)
// [
//   {
//     codec: 'mp3',
//     channels: 2,
//     sampleRate: '44100',
//     bitrate: '192000',
//     duration: '180.5',
//   }
// ]

// Convert with metadata
await audio('input.mp3', 'output.mp3', {
  codec: 'mp3',
  bitrate: '192k',
  channels: 2,
  sampleRate: 44100,
  metadata: {
    title: 'My Track',
    artist: 'Artist Name',
    album: 'Album Name',
    year: '2024',
  },
})

// Stream processing
const file = Bun.file('input.mp3')
const stream = file.stream()

await audioWithStreamInput(stream, 'output.wav', {
  codec: 'pcm_s16le',
  bitrate: '128k',
  channels: 1,
  sampleRate: 16000,
})

// Buffer processing
const arrayBuffer = await Bun.file('input.mp3').arrayBuffer()
const wavData = await audioWav(new Uint8Array(arrayBuffer))
await Bun.write('output.wav', wavData)

CLI Usage

Once installed globally or locally in your project, you can use audiox from the command line:

# Global installation
npm install -g @stacksjs/audiox

# Using npx with local installation
npx audiox [command] [options]

# Using bun
bunx audiox [command] [options]

Basic Commands

Convert audio files with default settings:

audiox convert input.mp3 output.wav

Get audio file information:

audiox info input.mp3

Convert Command Options

audiox convert <input> <output> [options]

Options:
  --codec <codec>           Audio codec (aac, mp3, pcm_s16le)
  --bitrate <bitrate>       Audio bitrate (e.g., "192k")
  --channels <number>       Number of channels (1, 2, 5.1, 7.1)
  --sample-rate <rate>      Sample rate (8000, 16000, 44100, 48000)
  --quality <number>        Audio quality setting
  -m, --metadata <data>     Set metadata (format: key=value)
  -v, --verbose            Enable verbose output

Examples

Convert to WAV with specific settings:

audiox convert input.mp3 output.wav --codec pcm_s16le --channels 1 --sample-rate 16000 --bitrate 128k

Convert to MP3 with metadata:

audiox convert input.wav output.mp3 --codec mp3 --bitrate 192k \
  --metadata title="My Song" \
  --metadata artist="Artist Name" \
  --metadata year=2024

Get detailed audio information including metadata:

audiox info input.mp3 --metadata title,artist,album,year

Configuration

You can create a audiox.config.js or audiox.config.ts file in your project root to set default options:

import type { AudioxOptions } from './src/types'

const config: AudioxOptions = {
  codec: 'mp3',
  bitrate: '192k',
  channels: 2,
  sampleRate: 44100,
  verbose: true
}

export default config

The CLI will automatically use these defaults unless overridden by command-line options.

Advanced Usage

Stream Processing with Custom Handlers

// Process audio with stream output handling
await audioWithStreamOut(
  'input.mp3',
  {
    onProcessDataFlushed: (chunk) => {
      // Handle each chunk of processed audio
      console.log('Processing chunk:', chunk?.length)
    },
    onProcessDataEnd: async (data) => {
      // Handle completed audio data
      await Bun.write('output.wav', data!)
    },
  },
  {
    codec: 'pcm_s16le',
    bitrate: '128k',
    channels: 1,
    sampleRate: 16000,
  },
)

Detailed Audio Information

// Get audio information including metadata
const audioInfo = await audioInfo('music.mp3', {
  metadataTags: ['title', 'artist', 'album', 'track', 'genre', 'year'],
})

// Example response:
// [
//   {
//     codec: 'mp3',
//     channels: 2,
//     sampleRate: '44100',
//     bitrate: '192000',
//     duration: '180.5',
//     metadata: {
//       title: 'Song Title',
//       artist: 'Artist Name',
//       album: 'Album Name',
//       track: '1',
//       genre: 'Pop',
//       year: '2024'
//     }
//   }
// ]

Configuration

Audiox can be configured using a audiox.config.ts (or audiox.config.js) file:

import type { AudioxConfig } from '@stacksjs/audiox'

const config: AudioxConfig = {
  verbose: true, // Enable detailed logging
  // Default audio settings
  codec: 'mp3',
  bitrate: '192k',
  channels: 2,
  sampleRate: 44100,
}

export default config

Available Options

interface AudioxOptions {
  codec?: 'aac' | 'mp3' | 'pcm_s16le' | string
  bitrate?: string // e.g., "192k"
  channels?: 1 | 2 | 5.1 | 7.1 | number
  sampleRate?: 8000 | 16000 | 44100 | 48000 | number
  quality?: number
  metadata?: {
    [key: string]: string
  }
  onError?: (error: unknown) => void
  verbose: boolean
}

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please review the Contributing Guide for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

Two things are true: Stacks OSS will always stay open-source, and we do love to receive postcards from wherever Stacks is used! We also publish them on our website.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

Credits

• bun-ffmpeg
• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙