📁 Sample Library

-- D1 Schema
CREATE TABLE samples (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  filename TEXT NOT NULL,
  category TEXT NOT NULL,
  subcategory TEXT,
  tags TEXT,  -- JSON array

  -- Audio properties
  duration_ms INTEGER NOT NULL,
  bpm REAL,
  key TEXT,
  sample_rate INTEGER DEFAULT 44100,
  bit_depth INTEGER DEFAULT 16,
  channels INTEGER DEFAULT 2,

  -- Analysis
  loudness_lufs REAL,
  peak_db REAL,
  spectral_centroid REAL,

  -- Display
  waveform_peaks TEXT,  -- JSON array for visualization
  color TEXT,  -- Category color hint

  -- Metadata
  source TEXT,  -- e.g., "government", "freesound", "user"
  license TEXT,
  attribution TEXT,

  -- Storage
  r2_key TEXT NOT NULL,
  file_size INTEGER,

  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_samples_category ON samples(category);
CREATE INDEX idx_samples_bpm ON samples(bpm);
CREATE INDEX idx_samples_key ON samples(key);

Samples are analyzed on upload to extract metadata automatically.

Analysis Functions

// analyze-sample.ts
async function analyzeSample(audioBuffer: ArrayBuffer): Promise<SampleAnalysis> {
  const audioContext = new OfflineAudioContext(2, 44100 * 30, 44100);
  const buffer = await audioContext.decodeAudioData(audioBuffer);

  // Extract features
  const channelData = buffer.getChannelData(0);

  return {
    duration_ms: Math.round(buffer.duration * 1000),
    sample_rate: buffer.sampleRate,
    channels: buffer.numberOfChannels,
    waveform_peaks: computePeaks(channelData, 100),
    loudness_lufs: calculateLUFS(channelData, buffer.sampleRate),
    peak_db: calculatePeakDb(channelData),
    bpm: await detectBPM(channelData, buffer.sampleRate),
    key: await detectKey(channelData, buffer.sampleRate)
  };
}

function computePeaks(data: Float32Array, numPeaks: number): number[] {
  const peaks: number[] = [];
  const samplesPerPeak = Math.floor(data.length / numPeaks);

  for (let i = 0; i < numPeaks; i++) {
    let max = 0;
    const start = i * samplesPerPeak;
    for (let j = start; j < start + samplesPerPeak && j < data.length; j++) {
      max = Math.max(max, Math.abs(data[j]));
    }
    peaks.push(max);
  }

  return peaks;
}

R2 Key Structure

samples/
  library/           # Built-in samples
    drums/
      kicks/
        808-deep-01.wav
        808-punchy-01.wav
      snares/
      hats/
    melodic/
    fx/
  user/              # User uploads
    {user_id}/
      {sample_id}.wav
  temp/              # Processing queue
    {job_id}.wav

The sample browser provides multiple ways to find sounds.

UI Components

• Search Bar: Natural language + filters
• Category Tree: Hierarchical navigation
• Tag Cloud: Quick tag filtering
• Waveform Preview: Visual + hover-to-play
• Drag-to-Timeline: Direct placement
• Favorites: Quick access list
• Recent: Recently used samples

Keyboard Shortcuts

Users can upload their own samples to their personal library.

Upload Flow

// upload.ts
async function uploadSample(file: File, userId: string) {
  // Validate
  if (!['audio/wav', 'audio/mp3', 'audio/mpeg'].includes(file.type)) {
    throw new Error('Unsupported format');
  }

  // Check quota
  const usage = await getUserStorageUsage(userId);
  if (usage + file.size > getUserStorageLimit(userId)) {
    throw new Error('Storage quota exceeded');
  }

  // Generate ID and key
  const sampleId = crypto.randomUUID();
  const r2Key = `samples/user/${userId}/${sampleId}.wav`;

  // Upload to R2
  await env.SAMPLES_BUCKET.put(r2Key, file.stream());

  // Analyze async
  await env.ANALYSIS_QUEUE.send({
    sampleId,
    r2Key,
    userId
  });

  return { sampleId, status: 'processing' };
}