@stacksjs/audiox

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)

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 💙

Changelog

v0.1.1...main

compare changes

🚀 Enhancements

• Allow for https boolean (6153960)

🏡 Chore

• Export cleanup (5565a04)
• Reset tests (a758d40)
• Update readme (10bdade)

❤️ Contributors

• Chris (@chrisbbreuer)