1. Basics

CARVE is a wave editor that runs entirely in your browser. Files are processed only on your device — nothing is uploaded or stored on a server. No install, no account.

• Open files: drop WAV / AIFF / FLAC / MP3 / OGG anywhere on the desktop, or use the Open… button (top right). Multiple files open as separate windows — one file, one window.
• Sample rates are preserved. A 48kHz file stays 48kHz; CARVE reads the exact rate from the file header and never silently resamples to the browser's output rate.
• The active window's file name is shown in the browser tab. Click a window's file name to copy it.

2. Navigation & selection

• Zoom: ＋ / − buttons zoom around the play cursor. Fit shows the whole file, Zoom Sel zooms to the selection. ↑ / ↓ (or V＋ / V−) zoom vertically — useful for inspecting quiet fades and tails.
• Overview strip (bottom of each window): shows the whole file; click or drag it to move the viewport.
• Click on the waveform sets the play cursor. ← / → nudge it by one pixel's worth of samples (Shift for ×10).
• Drag to select a range. Selection edges snap to the nearest zero crossing (within ±50ms) so cuts and loops stay click-free. Hold Shift while dragging to select raw positions with no snapping.
• Double-click between two markers (or between a marker and the file edge) to select that span exactly.
• The status bar shows length / selection / cursor — click any of them to copy the value.

3. Playback

• Space or ▶ — play from the cursor. With a selection active, playback loops the selection.
• Enter or ⏮ — play from the very start of the file, regardless of cursor or selection.
• Seam — loop seam check: plays up to one second before the loop end, then continues seamlessly from the loop start. Uses the selection if there is one, otherwise the whole file (end → start). This is the fastest way to audition whether a game-music loop joins cleanly.

4. Markers

• M — add a marker at the play cursor (up to 4 per file). Drag a marker head to move it.
• ⇧M — remove the marker nearest the cursor. Double-click a marker head to remove that one. Clear Mk removes all markers.
• Markers 1 and 2 (in time order) define the loop region written to OGG exports — see OGG loop tags.

5. Editing

Operations apply to the selection, or to the whole file when nothing is selected (where noted).

• Fade In / Fade Out — five curves: Linear, Smooth·fast, Smooth·slow, S-curve, S-curve·steep.
• Normalize — scales so the peak hits a target dBFS (presets 0 to −6, or type a value).
• Gain — amplify or attenuate by a fixed ±dB (−60 to +24). Warns if the result clips above 0dBFS.
• Delete (Del) — removes the selection and closes the gap.
• Copy (⌘C) / Paste (⌘V) — paste inserts at the cursor (it does not overwrite). Pasting between windows reconciles mono↔stereo automatically; sample-rate differences are noted but not converted.
• Extract → New — copies the selection into a new window. You can also just drag the selection out onto the desktop.
• Undo (⌘Z) / Redo (⇧⌘Z or ⌘Y) — 8 levels each, per window. Marker changes are not undoable.

6. Exporting

Pick a format in the status bar, then press Export.

OGG/MP3 encoding downloads a small WASM encoder on first use, so those two need a network connection once.

7. OGG loop tags

CARVE reads and writes the de-facto standard loop metadata for game audio: LOOPSTART and LOOPLENGTH stored as Vorbis comments, measured in samples.

• Export: if a window has two or more markers, the first two (in time order) are written as LOOPSTART = marker1 and LOOPLENGTH = marker2 − marker1. No markers → a plain OGG with no tags.
• Import: opening an OGG that carries LOOPSTART/LOOPLENGTH (or the LOOPEND variant) restores them as markers 1 and 2 automatically — a full round trip.

These tags are a community convention (popularized by RPG Maker), not part of the Vorbis specification. Players that don't understand them simply ignore them — the file remains a perfectly ordinary OGG.

8. Keyboard shortcuts

On Windows/Linux, use Ctrl in place of ⌘.

9. For programmers: implementing loop playback

9.1 The tag format

Loop points live in the Vorbis comment header (the same metadata block as ARTIST or TITLE) as plain KEY=VALUE strings:

LOOPSTART=132300      ; loop start, in samples
LOOPLENGTH=2646000    ; loop length, in samples

Some tools write LOOPEND instead of LOOPLENGTH; they are related by LOOPEND = LOOPSTART + LOOPLENGTH. A robust reader should accept both. Keys are case-insensitive per the Vorbis spec, but writing them in upper case is the convention.

Values are sample positions in the decoded PCM stream, at the file's own sample rate. To convert to seconds, divide by the sample rate. Because Vorbis is gapless (unlike MP3), sample positions in the source audio survive the encode exactly — sample 132300 in the OGG is sample 132300 in the original WAV.

9.2 The playback model

Intro-plus-loop playback, the standard game-BGM pattern:

play [0 .......... LOOPSTART .......... LOOPSTART+LOOPLENGTH)
                       ^                          |
                       └──────── jump back ───────┘

1. Play from sample 0 (the intro plays once).
2. When the play position reaches LOOPSTART + LOOPLENGTH, jump to LOOPSTART.
3. Repeat step 2 forever (until fade-out / stop).

The jump must be sample-accurate. Timer-based seeking ("check position every frame, seek when past the end") drifts and clicks; use your audio API's native loop-region support, or do the wraparound yourself inside the audio callback / buffer-fill loop.

9.3 Web Audio API (JavaScript)

The easiest target — AudioBufferSourceNode has native sample-accurate loop regions. Full working example, including a minimal tag reader:

// 1. Read LOOPSTART / LOOPLENGTH from the raw ogg bytes.
//    The comment header is near the start of the file; this scans Ogg pages
//    for the packet beginning "\x03vorbis" and walks the comment list.
function readLoopTags(bytes) {                      // bytes: Uint8Array
  const td = new TextDecoder();
  let off = 0, guard = 0;
  while (off + 27 <= bytes.length && guard++ < 16) {
    if (td.decode(bytes.subarray(off, off + 4)) !== 'OggS') return null;
    const nsegs = bytes[off + 26];
    let bodyLen = 0;
    for (let i = 0; i < nsegs; i++) bodyLen += bytes[off + 27 + i];
    const body = bytes.subarray(off + 27 + nsegs, off + 27 + nsegs + bodyLen);
    if (body[0] === 3 && td.decode(body.subarray(1, 7)) === 'vorbis') {
      const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
      let p = 7;
      p += 4 + dv.getUint32(p, true);               // skip vendor string
      const count = dv.getUint32(p, true); p += 4;
      let ls = null, ll = null, le = null;
      for (let i = 0; i < count; i++) {
        const len = dv.getUint32(p, true); p += 4;
        const s = td.decode(body.subarray(p, p + len)); p += len;
        const [k, v] = [s.slice(0, s.indexOf('=')).toUpperCase(),
                        parseInt(s.slice(s.indexOf('=') + 1), 10)];
        if (k === 'LOOPSTART') ls = v;
        if (k === 'LOOPLENGTH') ll = v;
        if (k === 'LOOPEND') le = v;
      }
      if (ls != null && ll == null && le != null) ll = le - ls;
      return ls != null && ll > 0 ? { loopStart: ls, loopLength: ll } : null;
    }
    off += 27 + nsegs + bodyLen;
  }
  return null;
}

// 2. Decode and play with a native loop region.
async function playLoopedBgm(url) {
  const ctx = new AudioContext();
  const raw = await (await fetch(url)).arrayBuffer();
  const tags = readLoopTags(new Uint8Array(raw));
  const buf = await ctx.decodeAudioData(raw);       // note: detaches `raw`

  const src = ctx.createBufferSource();
  src.buffer = buf;
  if (tags) {
    const sr = buf.sampleRate;                      // use the DECODED rate (see 9.6)
    src.loop = true;
    src.loopStart = tags.loopStart / sr;            // Web Audio wants seconds
    src.loopEnd = (tags.loopStart + tags.loopLength) / sr;
  } else {
    src.loop = true;                                // no tags: loop the whole file
  }
  src.connect(ctx.destination);
  src.start();                                      // intro plays once, then loops
  return src;                                       // keep it to call .stop() later
}

Read the tags before calling decodeAudioData — it detaches the ArrayBuffer.

9.4 C / C++ (libvorbisfile or stb_vorbis)

Get the comments, then wrap the read position yourself:

// --- reading tags with libvorbisfile ---
vorbis_comment *vc = ov_comment(&vf, -1);
long loop_start = -1, loop_len = -1, loop_end = -1;
for (int i = 0; i < vc->comments; i++) {
    const char *c = vc->user_comments[i];
    if (!strncasecmp(c, "LOOPSTART=", 10))  loop_start = atol(c + 10);
    if (!strncasecmp(c, "LOOPLENGTH=", 11)) loop_len   = atol(c + 11);
    if (!strncasecmp(c, "LOOPEND=", 8))     loop_end   = atol(c + 8);
}
if (loop_start >= 0 && loop_len < 0 && loop_end > 0)
    loop_len = loop_end - loop_start;

// --- streaming decode with a sample-accurate wrap ---
// Track the absolute sample position yourself. When the next read would
// cross loop_start + loop_len, read only up to the boundary, then:
ov_pcm_seek(&vf, loop_start);   // sample-accurate seek, then keep reading

With stb_vorbis the pattern is identical: parse stb_vorbis_get_comment() output, count samples as you pull them, and call stb_vorbis_seek(v, loop_start) at the boundary. Decode-ahead and buffer the seam so the jump happens inside your mixer, not on the audio thread's deadline.

9.5 Engines

• RPG Maker (VX Ace and later, including MV/MZ) — honors LOOPSTART/LOOPLENGTH natively. CARVE's output works as-is; this convention originated here.
• Godot — the OGG importer has loop settings; recent versions read these tags on import. Verify on your target version, and check the values in the import dock.
• Unity — no native support. Either parse the tags yourself (the ~40 lines in §9.3 port directly to C#) and drive two AudioSources / AudioClip.SetData, or use an asset-store plugin. AudioSource.loop alone loops the whole clip including the intro, which is not what you want.
• Custom engines (FMOD/Wwise pipelines) — middleware has its own loop-region systems; treat the tags as the source of truth in your build pipeline and bake them into the middleware project.

9.6 Pitfalls

• Samples, not seconds, not bytes. Convert with the sample rate only at the API boundary (like Web Audio's seconds-based loopStart).
• Don't resample before looping. If your pipeline resamples 48kHz → 44.1kHz, the tag values no longer point at the right samples. Scale them by newRate / origRate and round — and beware that rounding can move the point off its zero crossing. Best practice: loop first at the native rate, or author at the target rate.
• Decoder rate vs. tag rate. Some browser decodeAudioData implementations resample to the context rate. Compare the decoded buffer's sampleRate against your expectation; scale tag values if they differ (the §9.3 code divides by buf.sampleRate, which handles the seconds-conversion side, but sample-domain logic must scale positions too).
• Missing tags. Always define the fallback: loop the whole file, or play once. Never crash on an untagged OGG.
• Clean joins are authored, not coded. If the loop clicks even with a sample-accurate jump, the loop points aren't on matching zero crossings or the waveform doesn't continue naturally across the seam. Fix it in the editor (CARVE's zero-cross snapping and Seam check exist for exactly this).