A TypeScript-based audio processing library & CLI that wraps ffmpeg, helping you optimize audio files in Node.js/Bun environments.
- 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
bun install @stacksjs/audioxThere are two ways of using this tool: as a library or as a CLI.
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)// 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,
},
)// 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'
// }
// }
// ]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 configinterface 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
}bun testPlease see our releases page for more information on what has changed recently.
Please review the Contributing Guide for details.
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
For casual chit-chat with others using this package:
Join the Stacks Discord Server
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 🌎
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.
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙