Audio Track Combiner

A browser-based audio mixer for combining choir practice tracks (SATB) with independent left/right channel gain control. Built with Google Apps Script and the Web Audio API.

Copyright (c) 2026 Stuart Donaldson. Licensed under the MIT License.

Features

• 🎵 Load MP3s from Google Drive - Select a folder containing your choir tracks
• 🎚️ Pan/Level Controls - Adjust stereo positioning (pan) and overall volume (level) for each track independently
• 🔇 Solo/Mute - Isolate or silence individual tracks
• ▶️ Real-time Preview - Listen to your mix with play/pause/seek controls
• 💾 WAV Export - Render and download your final mix as a high-quality WAV file
• 🔊 Master Volume - Overall output control with built-in limiter to prevent clipping
• ℹ️ About Section - Comprehensive project information, features, technical details, and links

Project Structure

AudioTrackCombiner/
├── docs/
│   ├── requirements.md      # Detailed requirements document
│   ├── architecture.md      # System architecture and data flow
│   └── development-plan.md  # Milestones and testing strategy
└── src/
    ├── Code.js              # Apps Script backend
    ├── index.html           # Main HTML template
    ├── styles.css.html      # Stylesheet
    ├── ui.js.html           # UI logic
    ├── audioEngine.js.html  # Web Audio API mixer
    ├── wavEncoder.js.html   # WAV file encoder
    └── ffmpegExporter.js.html # Optional MP3 export

Prerequisites

For End Users

None! The Audio Track Combiner is a web application that runs entirely in your browser. No installation or setup required.

For Developers (Optional)

Node.js and npm are only needed if you want to use the development utilities:

• Node.js (v14+) - For running development scripts
• npm - Package manager for installing dependencies
• clasp - Google Apps Script CLI (optional, for deployment management)

Note: These tools are completely optional. You can deploy and use this project using only the Google Apps Script editor.

Deployment to Google Apps Script

Option A: Manual Copy-Paste

1. Go to script.google.com and create a new project
2. Rename the project to "Audio Track Combiner"
3. Replace the contents of Code.gs with the file from src/Code.js
4. Create new HTML files for each .html file in src/:
   • Click + → HTML → name it exactly (e.g., index, styles.css, ui.js, etc.)
   • Copy the contents from the corresponding file
5. Deploy:
   • Click Deploy → New deployment
   • Select Web app
   • Set "Execute as" to Me
   • Set "Who has access" to Anyone (or your preference)
   • Click Deploy
6. Copy the web app URL and open it in your browser

Option B: Using clasp (Command Line) - Optional

This method requires Node.js and clasp for command-line deployment. It's useful for developers who prefer CLI tools.

1. Install clasp globally:

   npm install -g @google/clasp

2. Login to Google:

   clasp login

3. Create a new Apps Script project:

   cd src
   clasp create --type webapp --title "Audio Track Combiner"

4. Push the files:

   clasp push

5. Open the project in browser:

   clasp open

6. Deploy from the Apps Script editor (see step 5 in Option A)

Updating Revision Date (Optional)

The revision date is automatically updated whenever you save .js or .html files in the src/ directory, thanks to the "Run on Save" VS Code extension.

If you don't have the extension installed, you can manually update the revision before deployment:

npm run update-revision

This updates src/version.html with the current date, ensuring users can see which version they're using.

Note: This is an optional development convenience. You can update version information manually or skip it entirely.

Managing Deployments (Optional)

The project includes a Node.js script to help manage Google Apps Script deployments:

npm run manage-deployments

This interactive script will:

• List all active deployments ordered by version (most recent first)
• Display @HEAD and the most recent deployment (which are never archived)
• Allow you to select older deployments to archive
• Confirm before archiving and show results

Prerequisites:

• Install clasp globally
• Login with clasp login
• Run from the project root directory

Note: This replaces the old PowerShell cleanup scripts and provides a safer, interactive way to manage deployments.

Configuration

Setting a Default Folder (Optional)

To automatically load a specific Google Drive folder when the app starts:

1. Open your Apps Script project in the Apps Script editor
2. Click Project Settings (gear icon)
3. In the "Script Properties" section, click Add property
4. Set Property: INITIAL_FOLDER_ID
5. Set Value: Your Google Drive folder ID (e.g., 1ABC123def456GHI789jkl)
6. Click Save

If this property is not set, the app will start with the folder input field open, allowing users to enter their own folder ID.

Security Note: Never commit folder IDs to version control. Use script properties for sensitive configuration.

Usage

1. Get your folder ID:

   • Open Google Drive and navigate to your folder containing MP3 files
   • Copy the folder ID from the URL: drive.google.com/drive/folders/[FOLDER_ID]

2. Load the tracks:

   • Paste the folder ID into the input field
   • Click "Load Folder"
   • Wait for all tracks to load (progress shown)

3. Adjust the mix:

   • Use the Pan slider (-1 to +1) to position each track in the stereo field
   • Use the Level slider (0 to 2x) to set the overall volume for each track
   • Click S to solo a track (hear only that track)
   • Click M to mute a track (silence that track)
   • Adjust Master Volume as needed

4. Preview your mix:

   • Click ▶️ Play to start playback
   • Use the seek bar to jump to different positions
   • Adjust gains in real-time while listening

5. Export:

   • Enter a filename (optional)
   • Click Export WAV to render and download

Technical Notes

Audio Processing

• All audio processing happens client-side in the browser
• Uses Web Audio API for real-time mixing and OfflineAudioContext for rendering
• Automatic normalization prevents clipping if combined gains exceed 1.0
• Shorter tracks are automatically padded with silence to match the longest track

File Size Limits

• Maximum file size: ~50MB per track (Apps Script limitation)
• Recommended: 3-8 minute tracks at 128-320kbps MP3

Browser Compatibility

• Chrome 90+, Firefox 88+, Edge 90+, Safari 14+
• Requires Web Audio API support

CORS Handling

• Audio files are transferred as base64 data URIs to bypass CORS restrictions
• This adds ~33% overhead but ensures compatibility

Optional: MP3 Export

The project includes an optional ffmpegExporter.js.html module for MP3 export. To enable:

1. The module will dynamically load ffmpeg.wasm (~25MB) when needed
2. Update the MP3 export button handler in ui.js.html to call FFmpegExporter.exportMp3()

Note: ffmpeg.wasm adds significant overhead and is optional. WAV export is recommended.

Troubleshooting

Issue	Solution
"Folder not found"	Check the folder ID is correct and you have access
"Permission denied"	Make sure the folder is shared with your Google account
No sound during preview	Click anywhere on the page first (AudioContext requires user gesture)
Export fails	Try with fewer/shorter tracks; check browser console for errors
Tracks out of sync	Ensure all source files have the same starting point

Recent Updates

v1.0 (February 2026)

• ✅ Fixed seeking bug - Resolved issue where clicking seek bar or backup buttons during playback would rewind to beginning instead of seeking to desired position
• ✅ UI improvements - Removed redundant my-part presets (40% vs 50% difference deemed insignificant)
• ✅ Added About section - Comprehensive modal with project information, features, technical details, and links
• ✅ Complete licensing - Added MIT license, copyright notices throughout codebase, and professional documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2026 Stuart Donaldson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.