add initial version of tab-downloader

songsterr/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Raw response format received when initiating a file download from Songsterr.
+ */
+export interface SongsterrDownloadResponse {
+  file: number[];       // Binary array representation of the downloaded file bytes
+  fileName: string;     // The original filename served by the server
+  contentType: string;  // The MIME type of the file
+}
+
+/**
+ * Basic metadata subset returned by Songsterr search endpoints.
+ */
+export interface SongsterrPartialMetadata {
+  title: string;        // Title of the song
+  songId: number;       // Global identifier for the song
+  artistId: number;     // Global identifier for the artist
+  artist: string;       // Artist name
+  byLinkUrl?: string;   // Optional absolute link URL
+}
+
+/**
+ * Represents metadata of an individual instrument track in Songsterr's state payload.
+ */
+export interface SongsterrStateMetaCurrentTrack {
+  partId: number;       // Part ID used to fetch the track-specific note payload JSON
+  instrumentId: number; // Instrument ID used for MIDI playback assignment
+  title?: string;       // Custom track title (alternative)
+  name?: string;        // Custom track name
+  tuning?: number[];    // Tuning offsets in semitones starting from highest pitch
+  isDrums?: boolean;    // Flag indicating if this is a percussion track
+}
+
+/**
+ * The top-level metadata container for the current song state scraped from Songsterr's HTML script block.
+ */
+export interface SongsterrStateMetaCurrent {
+  songId: number;       // Song ID
+  revisionId: number;   // Active musical notation revision ID
+  image: string;        // Storage hash/image suffix identifier on CloudFront CDNs
+  title: string;        // Title of the song
+  artist: string;       // Name of the artist
+  tracks: SongsterrStateMetaCurrentTrack[]; // Collection of tracks associated with this revision
+}
+
+/**
+ * A tempo variation marker inside the song's automation timeline.
+ */
+export interface SongsterrRevisionAutomationTempoPoint {
+  measure: number;      // 0-indexed measure where the tempo change occurs
+  position: number;     // Metric position within the measure
+  bpm: number;          // Beats Per Minute (tempo target)
+  type: number;         // Time division duration type index
+}
+
+/**
+ * Collection of performance automations (such as tempo changes) present in a revision.
+ */
+export interface SongsterrRevisionAutomations {
+  tempo?: SongsterrRevisionAutomationTempoPoint[];
+}
+
+/**
+ * Coordinate specifying a single point on a pitch bend diagram.
+ */
+export interface SongsterrRevisionBendPoint {
+  position: number;     // Horizontal offset on bend diagram (0 to 60)
+  tone: number;         // Pitch offset value (100 = 1 full tone, 50 = 1 semitone)
+}
+
+/**
+ * Pitch bend configuration payload for a note.
+ */
+export interface SongsterrRevisionBendPayload {
+  tone: number;         // Max bend tone value
+  points: SongsterrRevisionBendPoint[]; // Set of coordinate points defining the bend curve
+}
+
+/**
+ * Playback modification, articulation, or fret details of an individual note.
+ */
+export interface SongsterrRevisionNotePayload {
+  fret?: number;        // Fret number on the fretboard (0 = open string)
+  string?: number;      // 0-indexed string index (0 is typically the highest pitch string)
+  tie?: boolean;        // Identifies if this note is tied to the previous note
+  slide?: string;       // String code representing slide type ('shift', 'legato', 'below', etc.)
+  rest?: boolean;       // Identifies if the note is a rest
+  dead?: boolean;       // Identifies dead (muted) notes
+  ghost?: boolean;      // Identifies ghost/bracketed notes
+  hp?: boolean;         // Legato hammer-on or pull-off flag
+  staccato?: boolean;   // Articulation indicating a shortened note duration
+  accentuated?: boolean;// Flag indicating heavier picking velocity
+  vibrato?: boolean;    // Subtle pitch vibrato
+  wideVibrato?: boolean;// Intense pitch vibrato
+  harmonic?: string;    // Harmonic type ('natural', 'artificial', 'pinch', etc.)
+  harmonicFret?: number;// Fret location where the harmonic is initiated
+  bend?: SongsterrRevisionBendPayload; // Pitch bend details
+}
+
+/**
+ * Musical beat payload grouping multiple notes together played at the same instant.
+ */
+export interface SongsterrRevisionBeatPayload {
+  notes?: SongsterrRevisionNotePayload[]; // Collection of notes active in this beat
+  type?: number;        // Base beat duration category
+  duration?: [number, number]; // Fractional duration tuple [numerator, denominator]
+  dots?: number;        // Count of dots modifying the beat's length
+  text?: string | { text: string; width?: number }; // Custom lyric/annotation text on the staff
+  velocity?: string;    // MIDI dynamics code ('p', 'mp', 'f', etc.)
+  rest?: boolean;       // Flag identifying if this beat is a pure rest
+  palmMute?: boolean;   // Flag identifying if palm-muting is active for this beat
+  vibrato?: boolean;    // Beat-level vibrato
+  wideVibrato?: boolean;// Beat-level wide vibrato
+  vibratoWithTremoloBar?: string; // Tremolo bar vibrato depth code
+  pickStroke?: string;  // Picking direction ('up', 'down')
+  tuplet?: number;      // Tuplet factor (e.g., 3 for triplets, 5 for quintuplets)
+  tupletStart?: boolean;// Flag identifying the start of a tuplet grouping
+  tupletStop?: boolean; // Flag identifying the end of a tuplet grouping
+}
+
+/**
+ * Represents a vocal line/independent voice track containing sequential beats within a measure.
+ */
+export interface SongsterrRevisionVoicePayload {
+  beats?: SongsterrRevisionBeatPayload[]; // Beats sequenced inside this voice
+  rest?: boolean;       // Flag identifying if the voice is entirely silent
+}
+
+/**
+ * Represents a single measure (bar) in a track containing multiple voices.
+ */
+export interface SongsterrRevisionMeasurePayload {
+  voices?: SongsterrRevisionVoicePayload[]; // Independent musical voices in this bar
+  signature?: [number, number]; // Time signature tuple [numerator, denominator] (e.g. [4, 4])
+  marker?: string | { text: string; width?: number }; // Section marker name (e.g. "Verse", "Chorus")
+  repeatStart?: boolean;// Identifies if a repeat section opens at this measure
+  repeatCount?: number; // Count of repeat iterations
+  alternateEnding?: number; // Alternate ending bracket index/value
+  rest?: boolean;       // Identifies if the entire measure is silent
+}
+
+/**
+ * Complete musical score revision details for a single track.
+ */
+export interface SongsterrRevisionTrackPayload {
+  name?: string;        // Track name
+  instrumentId?: number;// Instrument playback configuration ID
+  tuning?: number[];    // Note offsets for each string
+  strings?: number;     // Number of strings on the instrument
+  measures: SongsterrRevisionMeasurePayload[]; // Complete sequence of measures (bars)
+  automations?: SongsterrRevisionAutomations; // Set of playback automations
+  songId?: number;      // Reference song identifier
+  revisionId?: number;  // Reference revision identifier
+  partId?: number;      // Reference part identifier
+}
+
+/**
+ * Warning payload generated during the parsing/conversion process.
+ */
+export interface ConversionWarning {
+  code: string;         // Unique warning code identifier (e.g., 'duration_approximated')
+  message: string;      // Human-readable warning description
+  location?: string;    // Code location indicating where the issue was hit (e.g., 'track:1|measure:12')
+}