guitarpro-parser 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Copyright 2026 Emilien Bevierre
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Minimal pitch utilities — inlined from GuitarWeaver's pitch.ts to make
+ * this package fully self-contained with zero external dependencies.
+ */
+/** Chromatic pitch class: 0 = C, 1 = C#/Db, ..., 11 = B */
+type PitchClass = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
+type Accidental = 'sharp' | 'flat' | 'natural';
+interface Note {
+    pitchClass: PitchClass;
+    name: string;
+    accidental: Accidental;
+    octave?: number;
+}
+/** Builds a Note from a pitch class, with optional octave and flat preference. */
+declare function noteFromPitchClass(pc: PitchClass, preferFlats?: boolean, octave?: number): Note;
+/** Converts MIDI note number to PitchClass. */
+declare function midiToPitchClass(midi: number): PitchClass;
+
+/**
+ * Copyright 2026 Emilien Bevierre
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Public types for parsed Guitar Pro file structures.
+ * These types are format-agnostic — all parsers (GPX, GP5, GP7) produce the same output.
+ */
+
+/** Duration values matching Guitar Pro's rhythm notation */
+type Duration = 'whole' | 'half' | 'quarter' | 'eighth' | '16th' | '32nd' | '64th' | '128th';
+/** A single note on a specific string/fret with technique annotations */
+interface TabNote {
+    string: number;
+    fret: number;
+    pitchClass: PitchClass;
+    noteName: string;
+    slide: number | null;
+    harmonic: string | null;
+    palmMute: boolean;
+    muted: boolean;
+    letRing: boolean;
+    bend: {
+        origin: number;
+        destination: number;
+        middle: number;
+    } | null;
+    tie: {
+        origin: boolean;
+        destination: boolean;
+    };
+    vibrato: string | null;
+    hammerOn: boolean;
+    pullOff: boolean;
+    tapped: boolean;
+    accent: number | null;
+}
+/** A beat = a rhythmic moment containing 0..N simultaneous notes */
+interface TabBeat {
+    index: number;
+    barIndex: number;
+    notes: TabNote[];
+    duration: Duration;
+    tuplet: {
+        num: number;
+        den: number;
+    } | null;
+    dotted: number;
+    isRest: boolean;
+    dynamic: string | null;
+    tempo: number;
+}
+/** A bar with time signature and key info */
+interface TabBar {
+    index: number;
+    timeSignature: {
+        numerator: number;
+        denominator: number;
+    };
+    keySignature: {
+        accidentalCount: number;
+        mode: 'major' | 'minor';
+    } | null;
+    section: {
+        letter?: string;
+        text?: string;
+    } | null;
+    beats: TabBeat[];
+    repeatStart: boolean;
+    repeatEnd: boolean;
+    repeatCount: number;
+}
+/** A track (instrument) with its tuning and bars */
+interface TabTrack {
+    id: string;
+    name: string;
+    shortName: string;
+    instrument: string | null;
+    tuning: Note[];
+    capoFret: number;
+    bars: TabBar[];
+}
+/** Top-level parsed song */
+interface TabSong {
+    title: string;
+    artist: string;
+    album: string;
+    tempo: number;
+    tracks: TabTrack[];
+}
+
+/**
+ * Copyright 2026 Emilien Bevierre
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Unified Guitar Pro file parser — dispatches to format-specific parsers
+ * based on file header detection.
+ *
+ * Supported formats:
+ * - .gpx  → BCFZ/BCFS container (Guitar Pro 6)
+ * - .gp   → ZIP container with Content/score.gpif (Guitar Pro 7+)
+ * - .gp5  → Legacy sequential binary (Guitar Pro 5)
+ *
+ * Pure, zero native dependencies.
+ */
+
+/** Detects file format from header bytes and filename. */
+declare function detectFormat(data: Uint8Array, fileName?: string): 'gpx' | 'gp7' | 'gp5';
+/**
+ * Parses any supported Guitar Pro file format into a TabSong.
+ * Detects format automatically from file header bytes.
+ *
+ * Supported: .gpx (GP6), .gp (GP7+), .gp5 (GP5)
+ */
+declare function parseTabFile(data: Uint8Array, fileName?: string): TabSong;
+
+/**
+ * Copyright 2026 Emilien Bevierre
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Converts a rhythm value to a beat fraction accounting for dots and tuplets. */
+declare function durationToBeats(duration: Duration, dotCount: number, tuplet: {
+    num: number;
+    den: number;
+} | null): number;
+/** Computes the duration in milliseconds for a beat at its tempo. */
+declare function beatDurationMs(beat: TabBeat): number;
+/** Transforms GPIF XML DOM into a TabSong. Exported for reuse by GP7+ ZIP parser. */
+declare function gpifToTabSong(doc: Document): TabSong;
+/** Parses a Guitar Pro .gpx file from raw bytes into a TabSong.
+ *  Pipeline: Uint8Array → BCFZ/BCFS decode → extract score.gpif → DOMParser → TabSong
+ */
+declare function parseGpxFile(data: Uint8Array): TabSong;
+
+/**
+ * Copyright 2026 Emilien Bevierre
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Parses a Guitar Pro 5 (.gp5) file from raw bytes into a TabSong. */
+declare function parseGp5File(data: Uint8Array): TabSong;
+
+export { type Accidental, type Duration, type Note, type PitchClass, type TabBar, type TabBeat, type TabNote, type TabSong, type TabTrack, beatDurationMs, detectFormat, durationToBeats, gpifToTabSong, midiToPitchClass, noteFromPitchClass, parseGp5File, parseGpxFile, parseTabFile };