CodecMerger: Web-Based Audio File Merger

Warning

this project was written with ai based on a proof of concept python file

Overview

CodecMerger is a web-based tool that allows users to merge multiple audio files directly in their browser. It aims to provide a simple drag-and-drop interface for combining audio tracks, leveraging client-side processing for speed and privacy. The core audio processing logic for aligning, mixing, and normalizing audio is inspired by concepts from a Python proof-of-concept.

The application is built with Svelte and Vite, using ffmpeg.wasm for all in-browser audio manipulation tasks. bun is used as the JavaScript runtime, bundler, and package manager.

Features

• Client-Side Processing: All audio processing happens in the user's browser; no files are uploaded to a server.
• Drag & Drop Interface: Easily add audio files to be processed.
• Multi-Format Support: Leverages ffmpeg.wasm to support a wide range of audio codecs and containers.
• Audio Alignment: (Planned) Implements techniques to align audio signals for coherent mixing.
• Audio Mixing: (Planned) Combines multiple audio tracks into one.
• Normalization: (Planned) Normalizes the final mixed audio to a standard peak level.
• Configurable ffmpeg.wasm: Option to toggle multi-threaded ffmpeg.wasm execution.
• GitHub Pages Deployment: Automated deployment pipeline using GitHub Actions.

Technologies Used

• Frontend: Svelte, SvelteKit
• Build Tool: Vite
• Audio Processing: ffmpeg.wasm (@ffmpeg/ffmpeg, @ffmpeg/core or @ffmpeg/core-mt, @ffmpeg/util)
• Runtime & Package Manager: Bun
• Styling: Plain CSS (as per +page.svelte)
• Linting/Formatting: ESLint, Prettier
• Version Control: Git, GitHub
• Deployment: GitHub Pages, GitHub Actions

Project Setup and Local Development

Prerequisites

• Bun (JavaScript runtime, bundler, package manager)

Installation

1. Clone the repository:

   git clone https://github.com/your-username/your-repo-name.git # <-- Update this URL
   cd your-repo-name

2. Install dependencies using Bun:

   bun install

Running Locally

To start the development server:

bun run dev

This will typically open the application in your web browser at http://localhost:5173.

Building for Production

To create a production build of the application:

bun run build

The output files will be generated in the build directory. This command is also used by the deployment script.

To preview the production build locally (after running bun run build):

bun run preview

Deployment to GitHub Pages

This project is configured for automated deployment to GitHub Pages using a GitHub Actions workflow (.github/workflows/deploy.yml).

How it works:

1. On pushes to the main branch (or your configured default branch), the GitHub Action will:
   • Checkout the code.
   • Set up Bun.
   • Install dependencies.
   • Update svelte.config.js and vite.config.ts with the correct repository name for the base path (using the GITHUB_REPOSITORY variable).
   • Build the SvelteKit application in production mode (which uses @sveltejs/adapter-static).
   • Upload the build artifact.
   • Deploy the artifact to GitHub Pages.

Repository Configuration for GitHub Pages:

• In your GitHub repository settings, under "Pages":
  • Set "Source" to "GitHub Actions".

Base Path Configuration:

The svelte.config.js and vite.config.ts files are configured to set the correct base path for GitHub Pages deployment. The workflow automatically updates a placeholder REPLACE_WITH_YOUR_REPO_NAME with your actual repository name. If you manually changed this placeholder to your repository name, the script will still run but won't find the placeholder to replace, which is fine.

Example (svelte.config.js):

paths: {
    base: process.env.NODE_ENV === 'production' ? '/your-repo-name' : '',
}

Example (vite.config.ts):

const repoName = 'your-repo-name';
// ...
base: mode === 'production' ? `/${repoName}/` : '/',

Important Notes

ffmpeg.wasm and Cross-Origin Isolation

• ffmpeg.wasm can utilize SharedArrayBuffer for multi-threaded performance (@ffmpeg/core-mt).
• SharedArrayBuffer requires specific HTTP headers for cross-origin isolation:
  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp
• The vite.config.ts includes these headers for the local development server.
• GitHub Pages does not allow setting custom HTTP headers. This means the multi-threaded version of ffmpeg.wasm might not work as expected or at all when deployed to GitHub Pages.
  • The application includes a toggle for multithreading. It is advisable to test this behavior on the deployed GitHub Pages site.
  • If multithreading is essential and does not work on GitHub Pages, consider alternative hosting platforms that allow custom headers (e.g., Netlify, Vercel, Cloudflare Pages) or investigate service worker-based solutions for COOP/COEP headers.

Bun Usage

This project exclusively uses bun as its JavaScript runtime, bundler, and package manager.

• DO NOT use npm, npx, yarn, or any other package managers.
• All scripts and commands should be executable via bun (e.g., bun install, bun run dev).
• The lockfile is bun.lockb.

---

This README was generated with assistance from an AI pair programmer.