sfxmix 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/README.md

@@ -0,0 +1,391 @@
+# 🎧 SfxMix
+
+**SfxMix** is a powerful and easy-to-use module for processing audio files using FFmpeg. It provides a fluent interface to concatenate, mix, insert silence, apply filters, and more! ✨
+
+---
+
+## 🚀 Features
+
+- **Concatenate** multiple audio files seamlessly.
+- **Mix** audio tracks with adjustable durations.
+- **Insert silence** at any point in your audio sequence.
+- **Apply filters** like echo, reverb, normalize, and more.
+- **Parameterizable filters** for fine-grained control.
+- **Fluent interface** for chaining multiple operations.
+
+---
+
+## 📦 Installation
+
+Before installing **SfxMix**, ensure that **FFmpeg** is installed and accessible in your system's PATH.
+
+### Install FFmpeg
+
+- **macOS:** Install via Homebrew
+  ```bash
+  brew install ffmpeg
+  ```
+- **Windows:** Download from [FFmpeg official website](https://ffmpeg.org/download.html).
+- **Linux:** Install via package manager
+  ```bash
+  sudo apt-get install ffmpeg
+  ```
+
+### Install SfxMix
+
+```bash
+npm install sfxmix
+```
+
+---
+
+## 📝 Usage
+
+```javascript
+const SfxMix = require('sfxmix');
+
+const processor = new SfxMix();
+
+processor
+  .add('intro.mp3')
+  .silence(2000) // 2 seconds of silence
+  .add('main.mp3')
+  .filter('normalize', { i: -14, tp: -2.0, lra: 7.0 })
+  .mix('background.mp3', { duration: 'first' })
+  .save('final_output.mp3')
+  .then(() => {
+    console.log('Audio processing completed successfully! 🎉');
+  })
+  .catch((err) => {
+    console.error('Error during audio processing:', err);
+  });
+```
+---
+
+## 🔧 Examples
+
+### 1. Concatenate and Mix with Background Music
+
+```javascript
+processor
+  .add('intro.mp3')
+  .add('chapter1.mp3')
+  .add('chapter2.mp3')
+  .mix('background_music.mp3', { duration: 'first' })
+  .save('audiobook_with_music.mp3');
+```
+
+### 2. Apply Multiple Filters
+
+```javascript
+processor
+  .add('voiceover.mp3')
+  .filter('normalize', { i: -14 })
+  .filter('equalizer', { frequency: 3000, width: 1000, gain: 5 })
+  .save('processed_voiceover.mp3');
+```
+
+### 3. Insert Silence Between Tracks
+
+```javascript
+processor
+  .add('track1.mp3')
+  .silence(2000)
+  .add('track2.mp3')
+  .silence(2000)
+  .add('track3.mp3')
+  .save('album_with_silence.mp3');
+```
+
+### 4. Apply Telephone Effect
+
+```javascript
+processor
+  .add('dialogue.mp3')
+  .filter('telephone')
+  .save('telephone_effect.mp3');
+```
+
+### 5. Adjust Volume and Add Echo
+
+```javascript
+processor
+  .add('announcement.mp3')
+  .filter('volume', { volume: 1.5 })
+  .filter('echo', { delay: 750, decay: 0.7 })
+  .save('enhanced_announcement.mp3');
+```
+
+---
+
+## 📖 API Documentation
+
+### Class: `SfxMix`
+
+#### Methods
+
+- [`add(input)`](#addinput)
+- [`mix(input, options)`](#mixinput-options)
+- [`silence(duration)`](#silenceduration)
+- [`filter(filterName, options)`](#filterfiltername-options)
+- [`save(output)`](#saveoutput)
+
+---
+
+### `add(input)`
+
+Adds an audio file to the processor for concatenation.
+
+- **Parameters:**
+  - `input` (string): Path to the audio file.
+- **Returns:** `SfxMix` (for chaining)
+
+**Example:**
+
+```javascript
+processor.add('part1.mp3').add('part2.mp3');
+```
+
+---
+
+### `mix(input, options)`
+
+Mixes an audio file with the current audio.
+
+- **Parameters:**
+  - `input` (string): Path to the audio file to mix.
+  - `options` (object): (Optional) Mixing options.
+    - `duration` (string): Determines the duration of the output. Can be `'longest'`, `'shortest'`, or `'first'`. Default is `'longest'`.
+- **Returns:** `SfxMix` (for chaining)
+
+**Example:**
+
+```javascript
+processor.mix('sound_effect.wav', { duration: 'first' });
+```
+
+---
+
+### `silence(duration)`
+
+Inserts silence into the audio sequence.
+
+- **Parameters:**
+  - `duration` (number): Duration of silence in milliseconds.
+- **Returns:** `SfxMix` (for chaining)
+
+**Example:**
+
+```javascript
+processor.silence(3000); // Inserts 3 seconds of silence
+```
+
+---
+
+### `filter(filterName, options)`
+
+Applies an audio filter to the current audio.
+
+- **Parameters:**
+  - `filterName` (string): Name of the filter to apply.
+  - `options` (object): (Optional) Filter-specific options.
+- **Returns:** `SfxMix` (for chaining)
+
+**Supported Filters:**
+
+- [`normalize`](#filternormalize)
+- [`telephone`](#filtertelephone)
+- [`echo`](#filterecho)
+- [`reverb`](#filterreverb)
+- [`highpass`](#filterhighpass)
+- [`lowpass`](#filterlowpass)
+- [`volume`](#filtervolume)
+- [`equalizer`](#filterequalizer)
+
+---
+
+### `save(output)`
+
+Processes the audio according to the specified actions and saves the result.
+
+- **Parameters:**
+  - `output` (string): Path to the output audio file.
+- **Returns:** `Promise` (resolves when processing is complete)
+
+**Example:**
+
+```javascript
+processor.save('output.mp3');
+```
+
+---
+
+## 🎛️ Filters
+
+### Filter: `normalize`
+
+Normalizes audio loudness to a specified target using the EBU R128 standard.
+
+- **Options:**
+  - `tp` (number): Maximum true peak level in dBTP (default: `-1.5`).
+  - `i` (number): Target integrated loudness in LUFS (default: `-16`).
+  - `lra` (number): Loudness range in LU (default: `11`).
+
+**Example:**
+
+```javascript
+processor.filter('normalize', { i: -14, tp: -2.0, lra: 7.0 });
+```
+
+---
+
+### Filter: `telephone`
+
+Applies a telephone effect by applying high-pass and low-pass filters.
+
+- **Options:**
+  - `lowFreq` (number): High-pass filter cutoff frequency in Hz (default: `300`).
+  - `highFreq` (number): Low-pass filter cutoff frequency in Hz (default: `3400`).
+
+**Example:**
+
+```javascript
+processor.filter('telephone', { lowFreq: 400, highFreq: 3000 });
+```
+
+---
+
+### Filter: `echo`
+
+Adds an echo effect to the audio.
+
+- **Options:**
+  - `delay` (number): Echo delay in milliseconds (default: `500`).
+  - `decay` (number): Echo decay factor between `0` and `1` (default: `0.5`).
+
+**Example:**
+
+```javascript
+processor.filter('echo', { delay: 1000, decay: 0.6 });
+```
+
+---
+
+### Filter: `reverb`
+
+Applies a reverb effect to the audio.
+
+- **Options:** None
+
+**Example:**
+
+```javascript
+processor.filter('reverb');
+```
+
+---
+
+### Filter: `highpass`
+
+Applies a high-pass filter to remove frequencies below the cutoff.
+
+- **Options:**
+  - `frequency` (number): Cutoff frequency in Hz.
+
+**Example:**
+
+```javascript
+processor.filter('highpass', { frequency: 1000 });
+```
+
+---
+
+### Filter: `lowpass`
+
+Applies a low-pass filter to remove frequencies above the cutoff.
+
+- **Options:**
+  - `frequency` (number): Cutoff frequency in Hz.
+
+**Example:**
+
+```javascript
+processor.filter('lowpass', { frequency: 2000 });
+```
+
+---
+
+### Filter: `volume`
+
+Adjusts the audio volume.
+
+- **Options:**
+  - `volume` (number): Volume multiplier (e.g., `0.5` for 50%).
+
+**Example:**
+
+```javascript
+processor.filter('volume', { volume: 0.8 });
+```
+
+---
+
+### Filter: `equalizer`
+
+Applies an equalizer effect to adjust specific frequencies.
+
+- **Options:**
+  - `frequency` (number): Center frequency in Hz.
+  - `width` (number): Bandwidth in Hz.
+  - `gain` (number): Gain in dB (positive to boost, negative to reduce).
+
+**Example:**
+
+```javascript
+processor.filter('equalizer', { frequency: 1000, width: 200, gain: -10 });
+```
+
+---
+
+## ⚠️ Important Notes
+
+- **FFmpeg Installation:** Ensure FFmpeg is installed and accessible in your system's PATH.
+- **File Permissions:** The module creates and deletes temporary files during processing. Ensure the application has the necessary permissions.
+- **Audio Formats:** The module assumes input files are in MP3 format. For other formats, adjust codec and format settings accordingly.
+- **Error Handling:** Always handle rejections from the `save()` method to catch any processing errors.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙌 Contributing
+
+Contributions are welcome! Feel free to submit a pull request or open an issue on GitHub.
+
+---
+
+## 💬 Support
+
+If you encounter any issues or have questions, please open an issue on the [GitHub repository](https://github.com/clasen/SfxMix/issues).
+
+---
+
+## 📚 References
+
+- [FFmpeg Documentation](https://ffmpeg.org/documentation.html)
+- [fluent-ffmpeg GitHub](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg)
+- [EBU R128 Loudness Recommendation](https://tech.ebu.ch/docs/r/r128.pdf)
+
+---
+
+## 🌟 Acknowledgments
+
+- Special thanks to the developers of FFmpeg and fluent-ffmpeg for their invaluable tools.
+
+---
+
+Enjoy processing your audio with **SfxMix**! 🎶✨

package/demo/demo_1.mjs

@@ -0,0 +1,16 @@
+import SfxMix from '../index.js';
+const sfx = new SfxMix();
+
+// Concatenate part1.mp3 and part2.mp3, 
+// then mix with glitches.wav for the duration of the concatenated audio
+await sfx
+    .add('part1.mp3')
+    .add('part2.mp3')
+    .mix('glitches.mp3', { duration: 'first' })
+    .save('demo1_add_add_mix.mp3')
+    .then(() => {
+        console.log('Successfully exported: demo1_add_add_mix.mp3');
+    })
+    .catch((error) => {
+        console.error('Error during audio processing:', error);
+    });

package/demo/demo_2.mjs

@@ -0,0 +1,14 @@
+import SfxMix from '../index.js';
+const sfx = new SfxMix();
+
+// Mix part1.mp3 with part2.mp3 and save the result
+try {
+    await sfx
+        .add('part1.mp3')
+        .mix('part2.mp3')
+        .save('demo2_add_mix.mp3');
+
+    console.log('Successfully exported: demo2_add_mix.mp3');
+} catch (error) {
+    console.error('Error exporting demo2_add_mix.mp3:', error);
+}

package/demo/demo_3.mjs

@@ -0,0 +1,19 @@
+import SfxMix from '../index.js';
+const sfx = new SfxMix();
+
+// Complex audio processing example
+// This demonstrates adding files, inserting silence, mixing, and applying filters
+
+try {
+    await sfx.add('part1.mp3')
+        .silence(2000) // Add 2 seconds of silence
+        .add('part2.mp3')
+        .mix('glitches.mp3', { duration: 'first' }) // Mix with glitches.mp3 for the duration of the first audio
+        .filter('telephone') // Apply telephone effect
+        .filter('normalize') // Normalize audio levels
+        .save('demo3_complex.mp3');
+    
+    console.log('Successfully exported: demo3_complex.mp3');
+} catch (error) {
+    console.error('Error exporting demo3_complex.mp3:', error);
+}

package/demo/demo_4.mjs

@@ -0,0 +1,19 @@
+import SfxMix from '../index.js';
+const sfx = new SfxMix();
+
+// Complex audio processing example
+// This demonstrates mixing multiple files, adding another file, and normalizing the audio
+
+try {
+    await sfx
+        .mix('part1.mp3')
+        .mix('part2.mp3')
+        .add('part2.mp3')
+        // Normalize the audio to -3 dB
+        .filter('normalize', { tp: -3 })
+        .save('demo4_mix_mix_add_normalized.mp3');
+
+    console.log('Successfully exported: demo4_mix_mix_add_normalized.mp3');
+} catch (error) {
+    console.error('Error exporting demo4_mix_mix_add_normalized.mp3:', error);
+}

package/index.js

@@ -0,0 +1,253 @@
+const ffmpeg = require('fluent-ffmpeg');
+const fs = require('fs');
+
+class SfxMix {
+    constructor() {
+        this.actions = [];
+        this.currentFile = null; // Keep track of the current audio file
+    }
+
+    add(input) {
+        this.actions.push({ type: 'add', input });
+        return this;
+    }
+
+    mix(input, options = {}) {
+        if (this.actions.length === 0) {
+            this.actions.push({ type: 'add', input });
+        } else {
+            this.actions.push({ type: 'mix', input, options });
+        }
+        return this;
+    }
+
+    silence(milliseconds) {
+        this.actions.push({ type: 'silence', duration: milliseconds });
+        return this;
+    }
+
+    filter(filterName, options = {}) {
+        this.actions.push({ type: 'filter', filterName, options });
+        return this;
+    }
+
+    save(output) {
+        return new Promise(async (resolve, reject) => {
+            try {
+                for (let action of this.actions) {
+                    if (action.type === 'add') {
+                        // Existing add logic
+                        if (this.currentFile == null) {
+                            this.currentFile = action.input;
+                        } else {
+                            const tempFile = `temp_concat_${Date.now()}.mp3`;
+                            await concatenateAudioFiles([this.currentFile, action.input], tempFile);
+                            if (isTempFile(this.currentFile)) {
+                                fs.unlinkSync(this.currentFile);
+                            }
+                            this.currentFile = tempFile;
+                        }
+                    } else if (action.type === 'mix') {
+                        // Existing mix logic
+                        if (this.currentFile == null) {
+                            throw new Error('No audio to mix with. Add or concatenate audio before mixing.');
+                        }
+                        const tempFile = `temp_mix_${Date.now()}.mp3`;
+                        await mixAudioFiles(this.currentFile, action.input, tempFile, action.options);
+                        if (isTempFile(this.currentFile)) {
+                            fs.unlinkSync(this.currentFile);
+                        }
+                        this.currentFile = tempFile;
+                    } else if (action.type === 'silence') {
+                        // Existing silence logic
+                        const tempSilenceFile = `temp_silence_${Date.now()}.mp3`;
+                        await generateSilence(action.duration, tempSilenceFile);
+                        if (this.currentFile == null) {
+                            this.currentFile = tempSilenceFile;
+                        } else {
+                            const tempFile = `temp_concat_${Date.now()}.mp3`;
+                            await concatenateAudioFiles([this.currentFile, tempSilenceFile], tempFile);
+                            if (isTempFile(this.currentFile)) {
+                                fs.unlinkSync(this.currentFile);
+                            }
+                            fs.unlinkSync(tempSilenceFile); // Remove the silence file
+                            this.currentFile = tempFile;
+                        }
+                    } else if (action.type === 'filter') {
+                        // New filter logic
+                        if (this.currentFile == null) {
+                            throw new Error('No audio to apply filter to. Add audio before applying filters.');
+                        }
+                        const tempFile = `temp_filter_${Date.now()}.mp3`;
+                        await applyFilter(this.currentFile, action.filterName, action.options, tempFile);
+                        if (isTempFile(this.currentFile)) {
+                            fs.unlinkSync(this.currentFile);
+                        }
+                        this.currentFile = tempFile;
+                    }
+                }
+                // Finalize output
+                fs.renameSync(this.currentFile, output);
+                resolve(output);
+            } catch (err) {
+                reject(err);
+            }
+        });
+    }
+}
+
+// Helper functions
+
+function isTempFile(filename) {
+    return (
+        filename.startsWith('temp_concat_') ||
+        filename.startsWith('temp_mix_') ||
+        filename.startsWith('temp_silence_') ||
+        filename.startsWith('temp_filter_')
+    );
+}
+
+function concatenateAudioFiles(inputFiles, outputFile) {
+    return new Promise((resolve, reject) => {
+        const concatList = inputFiles.map(file => `file '${file}'`).join('\n');
+        const concatFile = `concat_${Date.now()}.txt`;
+        fs.writeFileSync(concatFile, concatList);
+
+        ffmpeg()
+            .input(concatFile)
+            .inputOptions(['-f', 'concat', '-safe', '0'])
+            .outputOptions(['-c', 'copy'])
+            .output(outputFile)
+            .on('end', () => {
+                fs.unlinkSync(concatFile);
+                resolve();
+            })
+            .on('error', (err) => {
+                fs.unlinkSync(concatFile);
+                reject(err);
+            })
+            .run();
+    });
+}
+
+function mixAudioFiles(inputFile1, inputFile2, outputFile, options = {}) {
+    return new Promise((resolve, reject) => {
+        const durationOption = options.duration || 'longest'; // Default to 'longest'
+        ffmpeg()
+            .input(inputFile1)
+            .input(inputFile2)
+            .complexFilter([
+                {
+                    filter: 'amix',
+                    options: {
+                        inputs: 2,
+                        duration: durationOption,
+                    },
+                },
+            ])
+            .audioCodec('libmp3lame') // Ensure the codec is MP3
+            .format('mp3') // Ensure the format is MP3
+            .output(outputFile)
+            .on('end', () => resolve())
+            .on('error', (err) => reject(err))
+            .run();
+    });
+}
+
+function generateSilence(durationMs, outputFile) {
+    return new Promise((resolve, reject) => {
+        const durationSec = durationMs / 1000;
+        ffmpeg()
+            .input('anullsrc=channel_layout=stereo:sample_rate=44100')
+            .inputOptions(['-f', 'lavfi', '-t', `${durationSec}`])
+            .audioCodec('libmp3lame')
+            .format('mp3')
+            .output(outputFile)
+            .on('end', () => {
+                if (fs.existsSync(outputFile)) {
+                    resolve();
+                } else {
+                    reject(new Error(`Failed to generate silence file: ${outputFile}`));
+                }
+            })
+            .on('error', (err) => reject(err))
+            .run();
+    });
+}
+
+function applyFilter(inputFile, filterName, options, outputFile) {
+    return new Promise((resolve, reject) => {
+        const filterChain = getFilterChain(filterName, options);
+        if (!filterChain) {
+            return reject(new Error(`Unknown filter: ${filterName}`));
+        }
+
+        ffmpeg()
+            .input(inputFile)
+            .audioFilters(filterChain)
+            .audioCodec('libmp3lame')
+            .format('mp3')
+            .output(outputFile)
+            .on('end', () => resolve())
+            .on('error', (err) => reject(err))
+            .run();
+    });
+}
+
+function getFilterChain(filterName, options) {
+    switch (filterName) {
+        case 'normalize':
+            // Normalize audio using loudnorm filter with parameters
+            // Options: i (target integrated loudness), tp (true peak), lra (loudness range)
+            const i = options.i || -16;
+            const tp = options.tp || -1.5;
+            const lra = options.lra || 11;
+            return `loudnorm=I=${i}:TP=${tp}:LRA=${lra}:print_format=none`;
+        case 'telephone':
+            // Telephone effect with parameters
+            // Options: lowFreq (default 300), highFreq (default 3400)
+            const lowFreq = options.lowFreq || 300;
+            const highFreq = options.highFreq || 3400;
+            return `highpass=f=${lowFreq}, lowpass=f=${highFreq}`;
+        case 'echo':
+            // Default echo parameters: delay=500ms, decay=0.5
+            const echoDelay = options.delay || 500;
+            const echoDecay = options.decay || 0.5;
+            return `aecho=0.8:0.88:${echoDelay}:${echoDecay}`;
+        case 'reverb':
+            // Simple reverb effect
+            return 'areverb';
+        case 'highpass':
+            // High-pass filter: cutoff frequency in Hz
+            if (options.frequency) {
+                return `highpass=f=${options.frequency}`;
+            } else {
+                throw new Error('High-pass filter requires "frequency" option.');
+            }
+        case 'lowpass':
+            // Low-pass filter: cutoff frequency in Hz
+            if (options.frequency) {
+                return `lowpass=f=${options.frequency}`;
+            } else {
+                throw new Error('Low-pass filter requires "frequency" option.');
+            }
+        case 'volume':
+            // Volume adjustment: volume multiplier (e.g., 0.5 for 50%)
+            if (options.volume !== undefined) {
+                return `volume=${options.volume}`;
+            } else {
+                throw new Error('Volume filter requires "volume" option.');
+            }
+        case 'equalizer':
+            // Equalizer filter: frequency, width, gain
+            if (options.frequency && options.width && options.gain !== undefined) {
+                return `equalizer=f=${options.frequency}:width_type=h:width=${options.width}:g=${options.gain}`;
+            } else {
+                throw new Error('Equalizer filter requires "frequency", "width", and "gain" options.');
+            }
+        default:
+            return null;
+    }
+}
+
+module.exports = SfxMix;

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "sfxmix",
+    "description": "🎧 SfxMix - powerful and easy-to-use module for processing audio",
+    "version": "1.0.0",
+    "main": "index.js",
+    "dependencies": {
+        "fluent-ffmpeg": "^2.1.3"
+    },
+    "devDependencies": {},
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/clasen/SfxMix.git"
+    },
+    "keywords": [
+        "audio",
+        "concat",
+        "mix",
+        "silence",
+        "effects",
+        "filters",
+        "mp3",
+        "wav",
+        "echo",
+        "delay",
+        "telephone",
+        "equalizer",
+        "volume",
+        "normalize",
+        "ffmpeg",
+        "fluent-ffmpeg"
+    ],
+    "author": "Martin Clasen",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/clasen/SfxMix/issues"
+    }
+}