🎵 Vocal Deck – Advanced Audio Editor

A powerful, offline audio editing application built with React and Electron

Features • Installation • Usage • Contributing

---

📖 Overview

Vocal Deck is a professional-grade desktop audio editor that combines the power of React with Electron to deliver a seamless offline editing experience. Perfect for podcasters, musicians, content creators, and audio enthusiasts who need precise control over their audio files.

Why Vocal Deck?

✨ Non-destructive editing with unlimited undo/redo
🎨 Beautiful dark/light themed UI
🔊 Real-time waveform visualization
⚡ Offline processing - no internet required
🎛️ Professional audio effects and EQ controls
💾 Export to WAV or MP3 formats

---

🚀 Features

📁 File Management

• Multi-format support: Load WAV, MP3, and other audio formats
• Drag & drop interface: Easy file loading from anywhere
• File history: Access recently recorded and edited files
• Smart saving: Automatic file versioning to prevent overwrites

🌊 Waveform Visualization

• Real-time preview: Powered by wavesurfer.js
• Interactive timeline: Precise time markers and navigation
• Cursor dragging: Click and drag to scrub through audio
• Responsive design: Adapts to dark/light themes

✂️ Advanced Trimming

• Basic trim: Remove audio from start or end
  • Supports milliseconds, seconds, minutes, and hours
  • Left or right direction trimming
• Advanced trim: Remove any section precisely
  • Format: hh:mm:ss.ms (e.g., 00:01:30.500)
  • Cut out unwanted sections while keeping the rest
  • Millisecond precision for professional edits

🎛️ Equalizer

Adjust audio characteristics with real-time preview:

• Playback Speed: 0.5x → 2.0x (slow down or speed up)
• Bass Boost: -10dB → +10dB (enhance or reduce low frequencies)
• Pitch Shift: -12 → +12 semitones (change pitch without affecting speed)

🎙️ Voice Presets

One-click audio effects for creative transformation:

Effect	Description	Effect	Description
🤖 Robot	Mechanical voice	👽 Alien	Extraterrestrial speech
🐿️ Chipmunk	High-pitched, fast	🎈 Helium	Squeaky, light voice
🦇 Deep Bass	Low, powerful tone	😈 Demon	Dark, ominous voice
🌊 Echo Chamber	Spacious reverb	🌊 Underwater	Muffled, submerged
📞 Telephone	Lo-fi, band-limited	⛪ Cathedral	Large reverb space
🤫 Whisper	Quiet, airy voice	🎸 Distorted	Overdriven guitar-like
📢 Megaphone	Compressed, loud	🤖 Cyborg	Futuristic hybrid
📼 Old Tape	Vintage, degraded

🔄 Undo/Redo System

• Unlimited history: Every edit is tracked
• Non-destructive workflow: Safely experiment with effects
• Smart state management: Consistent across all editing operations
• Visual feedback: Buttons enable/disable based on history

🎙️ Built-in Recorder

• Direct recording: Record audio straight into the editor
• One-click save: Instantly start editing your recordings
• Automatic storage: Files saved to local VocalDeckData folder

💾 Export Options

• WAV format: Lossless, high-quality audio
• MP3 format: Compressed, smaller file size (requires FFmpeg)
• Smart naming: Automatic version suffixes prevent overwrites
• Quick access: Files saved to organized folders

---

📦 Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js >= 18.0.0 (Download)
• npm >= 9.0.0 (comes with Node.js)
• Git (Download)

Quick Start

1. Clone the repository

   git clone https://github.com/Nayan993/VocalDeck.git
   cd VocalDeck

2. Install dependencies

   npm install

3. Run in development mode

   # Terminal 1: Start React dev server
   npm start
   
   # Terminal 2: Start Electron wrapper
   npm run electron-dev

4. Build for production

   npm run build
   npm run electron

Optional: MP3 Export Setup

To enable MP3 export, install FFmpeg:

Windows:

npm install ffmpeg-static

macOS:

brew install ffmpeg

Linux:

sudo apt-get install ffmpeg

---

🎯 Usage Guide

1️⃣ Loading Audio

Method 1: Drag & Drop

• Drag any audio file directly into the center upload area

Method 2: Browse Files

• Click the "Browse" button and select your audio file

Method 3: Load from History

• Click on any file from the "Recorded Files" or "Updated Files" sidebar

2️⃣ Basic Trimming

1. Select trim direction (Left or Right)
2. Choose trim unit (milliseconds, seconds, minutes, hours)
3. Enter the amount to trim
4. Click Trim to apply

Example: Remove first 5 seconds

• Direction: Left
• Unit: Seconds
• Amount: 5

3️⃣ Advanced Trimming

1. Enter start time in format hh:mm:ss.ms
2. Enter end time in the same format
3. Click Apply to remove the section between start and end

Example: Remove 10 seconds starting at 1:30

• Start Time: 00:01:30.000
• End Time: 00:01:40.000

4️⃣ Applying EQ

1. Adjust the Speed slider (0.5x - 2.0x)
2. Modify Bass levels (-10dB to +10dB)
3. Change Pitch (-12 to +12 semitones)
4. Click Apply EQ to process

Tip: Preview changes before applying by playing the audio

5️⃣ Using Presets

Simply click any preset button to instantly apply the effect:

• Effects are processed offline for quality
• Changes are added to undo/redo history
• Waveform updates automatically

6️⃣ Saving Your Work

Save as WAV (Lossless)

• Click the first "Save" button
• Original quality preserved

Save as MP3 (Compressed)

• Click the second "Save" button
• Smaller file size, good for sharing

Note: Save buttons only activate after making edits

7️⃣ Undo/Redo

• Undo: Revert to previous state
• Redo: Reapply reverted changes
• Reset: Delete current file and start fresh

---

🏗️ Project Structure

VocalDeck/
│
├── public/                      # Static assets
│   └── index.html
│
├── src/
│   ├── assets/                  # Images, icons, audio samples
│   │   ├── microphone.png
│   │   ├── play-button.png
│   │   └── ...
│   │
│   ├── components/              # React components
│   │   ├── EditorNavbar.jsx     # Top navigation bar
│   │   ├── FileCard.jsx         # File history sidebar
│   │   ├── CenterCard.jsx       # Main waveform editor
│   │   ├── ButtonCard.jsx       # Playback controls
│   │   ├── AdvanceTrimCard.jsx  # Precision trimming
│   │   ├── EqualizerCard.jsx    # EQ controls
│   │   └── PresetsCard.jsx      # Voice effect presets
│   │
│   ├── pages/
│   │   └── EditorPage.jsx       # Main editor layout
│   │
│   ├── styles/                  # CSS modules
│   │   ├── EditorPage.css
│   │   ├── CenterCard.css
│   │   └── ...
│   │
│   ├── App.jsx                  # Root component
│   └── index.js                 # Entry point
│
├── electron/                    # Electron main process
│   └── main.js
│
├── package.json
└── README.md

---

🛠️ Technical Details

Audio Processing Pipeline

1. File Loading: Files are read as ArrayBuffer and converted to Blob
2. Waveform Rendering: wavesurfer.js creates visual representation
3. Audio Processing:
   • Uses Web Audio API's AudioContext
   • Offline rendering with OfflineAudioContext
   • Custom DSP for EQ and effects
4. WAV Encoding: Custom bufferToWave function creates valid WAV files
5. MP3 Encoding: FFmpeg converts WAV to MP3 (optional)

State Management

Global State (EditorPage.jsx)

• uploadedFile: Currently loaded audio file
• history: Array of all file states for undo/redo
• historyIndex: Current position in history
• hasUnsavedChanges: Boolean flag for save button

Component Communication

• Props drilling for shared state
• wavesurferRef for waveform access across components
• Consistent pushHistory function pattern

History Management

// Every edit follows this pattern:
const pushHistory = (file, markUnsaved = true) => {
  const newHistory = history.slice(0, historyIndex + 1);
  newHistory.push(file);
  setHistory(newHistory);
  setHistoryIndex(newHistory.length - 1);
  setUploadedFile(file);
  if (markUnsaved) setHasUnsavedChanges(true);
};

Rules:

• Initial uploads: markUnsaved = false
• Edits (trim, EQ, presets): markUnsaved = true
• Undo/redo: Navigate history without adding new states

---

🎨 Customization

Themes

Edit theme colors in component CSS files:

/* Dark theme */
.component.dark {
  background-color: #1e1e1e;
  color: #ffffff;
}

/* Light theme */
.component.light {
  background-color: #f0f0f0;
  color: #121212;
}

Adding New Presets

In PresetsCard.jsx, add to the applyPreset function:

case "YourEffect":
  // Apply custom audio processing
  const processed = customEffect(buffer);
  return processed;

---

🐛 Troubleshooting

Issue: MP3 export fails

Solution: Install FFmpeg (see Optional Setup above)

Issue: Waveform doesn't load

Solution: Ensure file format is supported (WAV, MP3, OGG)

Issue: Undo/Redo not working

Solution: Check console for history state logs, ensure all edit functions use pushHistory

Issue: Audio sounds distorted after effects

Solution: Reduce EQ intensity or try different presets

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository

   git fork https://github.com/Nayan993/VocalDeck.git

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Follow existing code style
   • Add comments for complex logic
   • Test thoroughly

4. Commit your changes

   git commit -m "Add amazing feature"

5. Push to your branch

   git push origin feature/amazing-feature

6. Open a Pull Request

   • Describe your changes clearly
   • Reference any related issues

Contribution Guidelines

• ✅ Write clean, readable code
• ✅ Test all features before submitting
• ✅ Update documentation if needed
• ✅ Follow the existing project structure
• ✅ Use meaningful commit messages

---

🙏 Acknowledgments

• WaveSurfer.js - Waveform visualization library
• React - UI framework
• Electron - Desktop app framework
• Web Audio API - Audio processing capabilities
• FFmpeg - Audio format conversion

---

📞 Contact & Support

• GitHub Issues: Report bugs or request features

---

Made with ❤️ by Sonic Smiths

⭐ Star this repo if you find it helpful!

⬆ Back to top