/**
 * 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')
}