konradre/video-production-skills / skills/mastering-audio
mastering-audio
VerifiedMaster audio files (especially Suno/Udio AI music) for streaming release with LUFS normalization, true peak limiting, and optional enhancements. Triggers — "master this", "master the track", "LUFS normalize", "optimize for streaming". Not for a spot's or film's delivery loudness — use video-finish-qc.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.4 KB |
| lib/dsp/constants.js | script | 1.8 KB |
| lib/dsp/dc-offset.js | script | 4.2 KB |
| lib/dsp/dynamic-leveler.js | script | 10.6 KB |
| lib/dsp/dynamic-processor.js | script | 16.8 KB |
| lib/dsp/exciter.js | script | 7.9 KB |
| lib/dsp/fft.js | script | 6.5 KB |
| lib/dsp/final-filters.js | script | 3.2 KB |
| lib/dsp/index.js | script | 3.2 KB |
| lib/dsp/limiter.js | script | 12.2 KB |
| lib/dsp/lufs.js | script | 5.7 KB |
| lib/dsp/multiband-saturation.js | script | 13.3 KB |
| lib/dsp/multiband-transient.js | script | 8.1 KB |
| lib/dsp/multiband.js | script | 8.2 KB |
| lib/dsp/normalizer.js | script | 4.5 KB |
| lib/dsp/saturation.js | script | 9.3 KB |
| lib/dsp/soft-clipper.js | script | 9.1 KB |
| lib/dsp/stereo.js | script | 8.8 KB |
| lib/dsp/transient.js | script | 7.9 KB |
| lib/dsp/true-peak.js | script | 2.6 KB |
| lib/dsp/utils.js | script | 4.4 KB |
| lib/src/audio-buffer-shim.js | script | 3.6 KB |
| lib/src/wav-encoder.js | script | 5.1 KB |
| package-lock.json | manifest | 611 B |
| package.json | manifest | 187 B |
| scripts/master.mjs | script | 15.2 KB |
scripts/master.mjs
View on GitHub#!/usr/bin/env node
/**
* Audio Mastering CLI Tool
*
* Processes audio files using the Web-Audio-Mastering DSP modules
* Optimized for AI-generated music (Suno, Udio, etc.)
*
* Usage:
* node master.mjs <input> [output] [options]
*
* Options:
* --analyze Only analyze, no processing
* --target-lufs N Target LUFS (default: -14)
* --ceiling N True peak ceiling in dB (default: -1)
* --deharsh Apply de-harsh processing (recommended for Suno)
* --add-air Add high-frequency sparkle
* --warmth Add tape warmth/saturation
* --punch Enhance transients
* --stereo-width N Stereo width percentage (default: 100)
* --bit-depth N Output bit depth: 16 or 24 (default: 24)
* --sample-rate N Output sample rate (default: 48000)
* --preset NAME Use preset: streaming, loud, dynamic, suno
* --json Output results as JSON
*/
import { execSync, spawn } from 'child_process';
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
import { basename, dirname, extname, join } from 'path';
import { fileURLToPath } from 'url';
// Initialize AudioBuffer shim before importing DSP modules
const __dirname = dirname(fileURLToPath(import.meta.url));
// Preflight: lib/dsp/fft.js imports the npm package `fft.js`, so a skill that has
// never had `npm install` run dies on the dynamic DSP import below with
// ERR_MODULE_NOT_FOUND naming an internal file — a raw Node stack trace that does
// not tell the caller the fix (measured 2026-07-19). Fail with the command instead.
// Runs in the module body, which is safe here because the two static imports that
// hoist above it (wav-encoder, audio-buffer-shim) have no imports of their own.
const SKILL_ROOT = join(__dirname, '..');
const missingDeps = (() => {
try {
const pkg = JSON.parse(readFileSync(join(SKILL_ROOT, 'package.json'), 'utf8'));
return Object.keys(pkg.dependencies ?? {})
.filter((dep) => !existsSync(join(SKILL_ROOT, 'node_modules', dep)));
} catch {
return []; // no/unreadable package.json — let the real import surface the error
}
})();
if (missingDeps.length > 0) {
console.error(`\nmastering-audio: missing npm ${missingDeps.length === 1 ? 'dependency' : 'dependencies'}: ${missingDeps.join(', ')}`);
console.error(`Install once, then re-run:\n npm install --prefix "${SKILL_ROOT}"\n`);
process.exit(1);
}
await import(join(__dirname, '../lib/src/audio-buffer-shim.js'));
// Import DSP modules (bundled in skill)
const DSP_PATH = join(__dirname, '../lib/dsp');
const {
measureLUFS,
findTruePeak,
normalizeToLUFS,
applyGain,
processHybridDynamic,
applyExciter,
applyTapeWarmth,
applyMultibandTransient,
adjustStereoWidth,
applyBassMono,
applyLookaheadLimiter,
applyFinalFilters,
detectDCOffset,
removeDCOffsetBuffer,
analyzeStereo
} = await import(join(DSP_PATH, 'index.js'));
import { encodeWAV } from '../lib/src/wav-encoder.js';
import { AudioBuffer, createAudioBufferFromInterleaved } from '../lib/src/audio-buffer-shim.js';
// ============================================================================
// Configuration & Presets
// ============================================================================
const PRESETS = {
streaming: {
targetLufs: -14,
ceiling: -1,
deharsh: true,
addAir: false,
warmth: false,
punch: false,
stereoWidth: 100,
bassMono: true
},
loud: {
targetLufs: -9,
ceiling: -0.3,
deharsh: true,
addAir: true,
warmth: true,
punch: true,
stereoWidth: 105,
bassMono: true
},
dynamic: {
targetLufs: -16,
ceiling: -1,
deharsh: false,
addAir: false,
warmth: false,
punch: false,
stereoWidth: 100,
bassMono: false
},
suno: {
// Optimized for Suno AI characteristics
targetLufs: -14,
ceiling: -1,
deharsh: true, // Reduce 2-4kHz harshness
addAir: true, // Restore high-end sparkle
warmth: false, // Suno already has warmth
punch: true, // Enhance transient definition
stereoWidth: 102, // Subtle widening
bassMono: true // Clean up stereo bass
}
};
// ============================================================================
// Audio I/O
// ============================================================================
/**
* Decode audio file to raw PCM using ffmpeg
*/
function decodeAudio(inputPath, targetSampleRate = 48000) {
const tempPcm = `/tmp/audio_decode_${Date.now()}.raw`;
try {
// Decode to 32-bit float stereo PCM
execSync(
`ffmpeg -y -i "${inputPath}" -f f32le -acodec pcm_f32le -ar ${targetSampleRate} -ac 2 "${tempPcm}"`,
{ stdio: 'pipe' }
);
const rawData = readFileSync(tempPcm);
const float32Data = new Float32Array(rawData.buffer, rawData.byteOffset, rawData.length / 4);
// Clean up temp file
execSync(`rm "${tempPcm}"`, { stdio: 'pipe' });
return createAudioBufferFromInterleaved(float32Data, 2, targetSampleRate);
} catch (error) {
throw new Error(`Failed to decode audio: ${error.message}`);
}
}
/**
* Get audio duration using ffprobe
*/
function getAudioInfo(inputPath) {
try {
const result = execSync(
`ffprobe -v quiet -print_format json -show_format -show_streams "${inputPath}"`,
{ encoding: 'utf8' }
);
return JSON.parse(result);
} catch (error) {
return null;
}
}
// ============================================================================
// Analysis
// ============================================================================
/**
* Analyze audio and return metrics
*/
function analyzeAudio(audioBuffer) {
const lufs = measureLUFS(audioBuffer);
const truePeak = findTruePeak(audioBuffer);
const stereo = analyzeStereo(audioBuffer);
const dcOffset = detectDCOffset(audioBuffer.getChannelData(0));
// Detect potential issues
const issues = [];
if (lufs > -10) {
issues.push({ type: 'loudness', severity: 'high', message: `Very loud (${lufs.toFixed(1)} LUFS) - may cause streaming normalization` });
} else if (lufs > -12) {
issues.push({ type: 'loudness', severity: 'medium', message: `Loud (${lufs.toFixed(1)} LUFS) - consider reducing for streaming` });
}
if (truePeak > 0) {
issues.push({ type: 'clipping', severity: 'high', message: `Clipping detected (${truePeak.toFixed(1)} dBTP)` });
} else if (truePeak > -0.5) {
issues.push({ type: 'headroom', severity: 'medium', message: `Low headroom (${truePeak.toFixed(1)} dBTP)` });
}
if (Math.abs(dcOffset) > 0.01) {
issues.push({ type: 'dc_offset', severity: 'low', message: `DC offset detected (${(dcOffset * 100).toFixed(2)}%)` });
}
return {
lufs: lufs,
truePeak: truePeak,
stereoCorrelation: stereo?.correlation || 0,
stereoWidth: stereo?.width || 1,
dcOffset: dcOffset,
duration: audioBuffer.duration,
sampleRate: audioBuffer.sampleRate,
channels: audioBuffer.numberOfChannels,
issues: issues
};
}
// ============================================================================
// Processing
// ============================================================================
/**
* Apply full mastering chain
*/
async function masterAudio(audioBuffer, options, onProgress = null) {
let processed = audioBuffer;
const log = options.json ? () => {} : console.log;
const report = (step, msg) => {
log(`[${step}] ${msg}`);
if (onProgress) onProgress(step, msg);
};
// Step 1: Remove DC offset if present
const dcOffset = detectDCOffset(processed.getChannelData(0));
if (Math.abs(dcOffset) > 0.001) {
report('DC', `Removing DC offset (${(dcOffset * 100).toFixed(3)}%)`);
processed = removeDCOffsetBuffer(processed);
}
// Step 2: De-harsh (multiband dynamics + dynamic EQ)
if (options.deharsh) {
report('DEHARSH', 'Applying hybrid dynamic processor');
processed = await processHybridDynamic(processed, 'mastering');
}
// Step 3: Exciter (add air/sparkle)
if (options.addAir) {
report('EXCITER', 'Adding high-frequency enhancement');
processed = await applyExciter(processed);
}
// Step 4: Tape warmth (multiband saturation)
if (options.warmth) {
report('WARMTH', 'Applying tape warmth');
processed = await applyTapeWarmth(processed);
}
// Step 5: Transient enhancement (punch)
if (options.punch) {
report('PUNCH', 'Enhancing transients');
processed = await applyMultibandTransient(processed);
}
// Step 6: Stereo processing
if (options.stereoWidth !== 100) {
report('STEREO', `Adjusting stereo width to ${options.stereoWidth}%`);
processed = adjustStereoWidth(processed, options.stereoWidth / 100);
}
// Step 7: Bass mono (if enabled)
if (options.bassMono) {
report('BASS', 'Applying mono bass (< 200 Hz)');
processed = applyBassMono(processed, 200);
}
// Step 8: Final filters (high-pass 30Hz, low-pass 18kHz)
report('FILTERS', 'Applying final filters');
processed = applyFinalFilters(processed, { highPass: 30, lowPass: 18000 });
// Step 9: LUFS normalization
const preLufs = measureLUFS(processed);
report('NORMALIZE', `Normalizing: ${preLufs.toFixed(1)} LUFS → ${options.targetLufs} LUFS`);
processed = normalizeToLUFS(processed, options.targetLufs, options.ceiling, { skipLimiter: true });
// Step 10: True peak limiting
const ceilingLinear = Math.pow(10, options.ceiling / 20);
report('LIMITER', `Applying lookahead limiter (ceiling: ${options.ceiling} dBTP)`);
processed = applyLookaheadLimiter(processed, ceilingLinear, 3, 100);
return processed;
}
// ============================================================================
// CLI Interface
// ============================================================================
function parseArgs(args) {
const options = {
input: null,
output: null,
analyzeOnly: false,
targetLufs: -14,
ceiling: -1,
deharsh: false,
addAir: false,
warmth: false,
punch: false,
stereoWidth: 100,
bassMono: true,
bitDepth: 24,
sampleRate: 48000,
preset: null,
json: false
};
const positional = [];
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === '--analyze') {
options.analyzeOnly = true;
} else if (arg === '--target-lufs') {
options.targetLufs = parseFloat(args[++i]);
} else if (arg === '--ceiling') {
options.ceiling = parseFloat(args[++i]);
} else if (arg === '--deharsh') {
options.deharsh = true;
} else if (arg === '--add-air') {
options.addAir = true;
} else if (arg === '--warmth') {
options.warmth = true;
} else if (arg === '--punch') {
options.punch = true;
} else if (arg === '--stereo-width') {
options.stereoWidth = parseFloat(args[++i]);
} else if (arg === '--bit-depth') {
options.bitDepth = parseInt(args[++i]);
} else if (arg === '--sample-rate') {
options.sampleRate = parseInt(args[++i]);
} else if (arg === '--preset') {
options.preset = args[++i];
} else if (arg === '--json') {
options.json = true;
} else if (arg === '--help' || arg === '-h') {
console.log(`
Audio Mastering CLI - Optimized for AI-generated music
Usage: node master.mjs <input> [output] [options]
Options:
--analyze Only analyze, no processing
--target-lufs N Target LUFS (default: -14)
--ceiling N True peak ceiling in dB (default: -1)
--deharsh Apply de-harsh processing
--add-air Add high-frequency sparkle
--warmth Add tape warmth/saturation
--punch Enhance transients
--stereo-width N Stereo width % (default: 100)
--bit-depth N 16 or 24 (default: 24)
--sample-rate N Output sample rate (default: 48000)
--preset NAME streaming, loud, dynamic, suno
--json Output as JSON
Examples:
node master.mjs song.mp3 --analyze
node master.mjs song.mp3 song_mastered.wav --preset suno
node master.mjs song.mp3 --deharsh --add-air --target-lufs -14
`);
process.exit(0);
} else if (!arg.startsWith('-')) {
positional.push(arg);
}
}
options.input = positional[0];
options.output = positional[1];
// Apply preset if specified
if (options.preset && PRESETS[options.preset]) {
Object.assign(options, PRESETS[options.preset]);
}
return options;
}
async function main() {
const args = process.argv.slice(2);
if (args.length === 0) {
console.error('Usage: node master.mjs <input> [output] [options]');
console.error('Use --help for more information');
process.exit(1);
}
const options = parseArgs(args);
if (!options.input) {
console.error('Error: Input file required');
process.exit(1);
}
if (!existsSync(options.input)) {
console.error(`Error: Input file not found: ${options.input}`);
process.exit(1);
}
const log = options.json ? () => {} : console.log;
// Get file info
const info = getAudioInfo(options.input);
log(`\nInput: ${options.input}`);
if (info?.format?.duration) {
log(`Duration: ${parseFloat(info.format.duration).toFixed(1)}s`);
}
// Decode audio
log('\nDecoding audio...');
const audioBuffer = decodeAudio(options.input, options.sampleRate);
log(`Loaded: ${audioBuffer.duration.toFixed(1)}s, ${audioBuffer.sampleRate}Hz, ${audioBuffer.numberOfChannels}ch`);
// Analyze
log('\nAnalyzing...');
const analysis = analyzeAudio(audioBuffer);
if (options.json && options.analyzeOnly) {
console.log(JSON.stringify({ analysis }, null, 2));
return;
}
log(` LUFS: ${analysis.lufs.toFixed(1)}`);
log(` True Peak: ${analysis.truePeak.toFixed(1)} dBTP`);
log(` Stereo Width: ${(analysis.stereoWidth * 100).toFixed(0)}%`);
if (analysis.issues.length > 0) {
log('\nDetected issues:');
for (const issue of analysis.issues) {
log(` [${issue.severity.toUpperCase()}] ${issue.message}`);
}
}
if (options.analyzeOnly) {
return;
}
// Generate output path if not specified
if (!options.output) {
const dir = dirname(options.input);
const base = basename(options.input, extname(options.input));
options.output = join(dir, `${base}_mastered.wav`);
}
// Process
log('\nProcessing...');
const processed = await masterAudio(audioBuffer, options);
// Final analysis
const finalAnalysis = analyzeAudio(processed);
log('\nFinal:');
log(` LUFS: ${finalAnalysis.lufs.toFixed(1)}`);
log(` True Peak: ${finalAnalysis.truePeak.toFixed(1)} dBTP`);
// Encode and save
log('\nEncoding WAV...');
const wavBuffer = encodeWAV(processed, {
bitDepth: options.bitDepth,
sampleRate: options.sampleRate
});
writeFileSync(options.output, wavBuffer);
log(`\nSaved: ${options.output}`);
log(` Size: ${(wavBuffer.length / 1024 / 1024).toFixed(1)} MB`);
log(` Format: ${options.sampleRate}Hz / ${options.bitDepth}-bit`);
if (options.json) {
console.log(JSON.stringify({
input: options.input,
output: options.output,
before: analysis,
after: finalAnalysis,
settings: {
targetLufs: options.targetLufs,
ceiling: options.ceiling,
deharsh: options.deharsh,
addAir: options.addAir,
warmth: options.warmth,
punch: options.punch,
stereoWidth: options.stereoWidth
}
}, null, 2));
}
}
main().catch(err => {
console.error('Error:', err.message);
process.exit(1);
});
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |