guitarpro-parser

Parse Guitar Pro files (.gp, .gpx, .gp5, .gp3) in JavaScript. Works in Node.js and browsers. No native dependencies.

Installation

npm install guitarpro-parser

Quick Start

Parse a file

import { parseTabFile } from 'guitarpro-parser';
import { readFileSync } from 'fs';

const data = new Uint8Array(readFileSync('song.gp'));
const song = parseTabFile(data);

Get song metadata

console.log(song.title);   // "Beyond Heavens Gate"
console.log(song.artist);  // "Unprocessed"
console.log(song.album);   // "Angel"
console.log(song.tempo);   // 140

Get tracks and tunings

for (const track of song.tracks) {
  console.log(track.name);  // "Guitar 1"
  
  // Tuning as Note[] (low to high)
  const tuningNames = track.tuning.map(note => note.name);
  console.log(tuningNames);  // ["E", "A", "D", "G", "B", "E"]
  
  // Raw MIDI pitch numbers per string (useful for audio synthesis)
  console.log(track.tuningMidi);  // [40, 45, 50, 55, 59, 64]
  
  console.log(track.capoFret);  // 0
  console.log(track.bars.length);  // 92
}

Get notes from a bar

const track = song.tracks[0];
const bar = track.bars[0];

// Time signature
console.log(bar.timeSignature);  // { numerator: 4, denominator: 4 }

// Iterate through beats
for (const beat of bar.beats) {
  if (beat.isRest) continue;
  
  console.log(beat.duration);  // "quarter", "eighth", "16th", etc.
  
  // Get all notes in this beat
  for (const note of beat.notes) {
    console.log(`String ${note.string}, Fret ${note.fret}`);  // "String 2, Fret 5"
    console.log(note.noteName);  // "A"
    
    // Techniques
    if (note.bend) console.log('Bend:', note.bend.destination);
    if (note.slide) console.log('Slide');
    if (note.hammerOn) console.log('Hammer-on');
    if (note.palmMute) console.log('Palm mute');
  }
}

Browser usage

// From file input
const file = input.files[0];
const data = new Uint8Array(await file.arrayBuffer());
const song = parseTabFile(data, file.name);

// From URL
const response = await fetch('song.gp');
const data = new Uint8Array(await response.arrayBuffer());
const song = parseTabFile(data);

Supported Formats

| Format | Extension | Guitar Pro Version | |--------|-----------|-------------------| | GP7+ | .gp | Guitar Pro 7, 8 | | GPX | .gpx | Guitar Pro 6 | | GP5 | .gp5 | Guitar Pro 5 | | GP3 | .gp3 | Guitar Pro 3 |

Format is auto-detected from file header.

API Reference

Main parser. Auto-detects format and returns parsed song.

parseTabFile(data: Uint8Array, fileName?: string): TabSong

Detect format without parsing.

detectFormat(data: Uint8Array, fileName?: string): 'gpx' | 'gp7' | 'gp5' | 'gp3'

Format-specific parsers if you know the format in advance.

parseGpxFile(data: Uint8Array): TabSong
parseGp5File(data: Uint8Array): TabSong
parseGp3File(data: Uint8Array): TabSong

Convert rhythm to beat fractions (quarter note = 1.0).

durationToBeats('quarter', 0, null);  // 1.0
durationToBeats('quarter', 1, null);  // 1.5 (dotted)
durationToBeats('quarter', 0, { num: 3, den: 2 });  // 0.666... (triplet)

Get beat duration in milliseconds at its tempo.

beatDurationMs(beat: TabBeat): number

Calculate musical beat position within a bar (1-based).

musicalBeatPosition(bar: TabBar, beatIdx: number): number

Get the number of musical beats in a bar.

barMusicalBeatCount(bar: TabBar): number

Type Definitions

interface TabSong {
  title: string;
  artist: string;
  album: string;
  tempo: number;
  tracks: TabTrack[];
}

interface TabTrack {
  id: string;
  name: string;
  tuning: Note[];           // Low to high
  tuningMidi: number[];     // Raw MIDI pitch numbers per string (index 0 = lowest string)
  capoFret: number;
  bars: TabBar[];
}

interface TabBar {
  index: number;
  timeSignature: { numerator: number; denominator: number };
  beats: TabBeat[];
  repeatStart: boolean;
  repeatEnd: boolean;
}

interface TabBeat {
  notes: TabNote[];
  duration: Duration;       // "whole" | "half" | "quarter" | "eighth" | "16th" | ...
  tuplet: { num: number; den: number } | null;
  dotted: number;
  isRest: boolean;
  tempo: number;
}

interface TabNote {
  string: number;           // 0-based, 0 = lowest string
  fret: number;
  noteName: string;         // "E", "F#", "Bb", etc.
  pitchClass: PitchClass;   // 0-11 (C=0)
  
  // Techniques
  bend: { origin: number; destination: number; middle: number } | null;
  slide: number | null;
  harmonic: string | null;
  vibrato: string | null;
  hammerOn: boolean;
  pullOff: boolean;
  palmMute: boolean;
  letRing: boolean;
  tapped: boolean;
  muted: boolean;
  tie: { origin: boolean; destination: boolean };
  accent: number | null;
}

interface Note {
  pitchClass: PitchClass;   // 0-11
  name: string;             // "E", "F#", "Bb"
  accidental: 'sharp' | 'flat' | 'natural';
}