add initial version of tab-downloader
This commit is contained in:
880
songsterr/songsterr-to-alphatab.converter.ts
Normal file
880
songsterr/songsterr-to-alphatab.converter.ts
Normal file
@@ -0,0 +1,880 @@
|
||||
import * as alphaTab from '@coderline/alphatab';
|
||||
import type {
|
||||
ConversionWarning,
|
||||
SongsterrRevisionAutomationTempoPoint,
|
||||
SongsterrRevisionBeatPayload,
|
||||
SongsterrRevisionNotePayload,
|
||||
SongsterrRevisionTrackPayload,
|
||||
SongsterrRevisionVoicePayload,
|
||||
SongsterrStateMetaCurrent,
|
||||
SongsterrStateMetaCurrentTrack
|
||||
} from './types.ts';
|
||||
import { mapSongsterrDuration } from './duration-mapper.ts';
|
||||
import { mapSongsterrInstrumentToPlayback } from './instrument-map.ts';
|
||||
|
||||
/**
|
||||
* Input structure matching metadata to track-specific note revision payloads.
|
||||
*/
|
||||
export interface SongsterrRevisionTrackInput {
|
||||
trackMeta: SongsterrStateMetaCurrentTrack;
|
||||
revision: SongsterrRevisionTrackPayload;
|
||||
}
|
||||
|
||||
/**
|
||||
* Top-level structure containing the inputs required to run the conversion process.
|
||||
*/
|
||||
interface SongsterrToGpInput {
|
||||
meta: SongsterrStateMetaCurrent;
|
||||
revisions: SongsterrRevisionTrackInput[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Output payload containing the compiled file bytes and conversion warnings.
|
||||
*/
|
||||
interface SongsterrToAlphaTabOutput {
|
||||
data: Uint8Array;
|
||||
warnings: ConversionWarning[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Intermediary result returned after compiling alphaTab models in memory.
|
||||
*/
|
||||
interface BuildScoreResult {
|
||||
score: alphaTab.model.Score;
|
||||
settings: alphaTab.Settings;
|
||||
warnings: ConversionWarning[];
|
||||
}
|
||||
|
||||
// Cap to prevent warning list overhead or infinite feedback loops
|
||||
const MAX_WARNINGS = 200;
|
||||
|
||||
// Mapping of Songsterr dynamics string descriptors to standard alphaTab DynamicValues
|
||||
const velocityToDynamicMap: Record<string, alphaTab.model.DynamicValue> = {
|
||||
ppp: alphaTab.model.DynamicValue.PPP,
|
||||
pp: alphaTab.model.DynamicValue.PP,
|
||||
p: alphaTab.model.DynamicValue.P,
|
||||
mp: alphaTab.model.DynamicValue.MP,
|
||||
mf: alphaTab.model.DynamicValue.MF,
|
||||
f: alphaTab.model.DynamicValue.F,
|
||||
ff: alphaTab.model.DynamicValue.FF,
|
||||
fff: alphaTab.model.DynamicValue.FFF
|
||||
};
|
||||
|
||||
// Mapping of Songsterr harmonic type descriptors to standard alphaTab HarmonicTypes
|
||||
const harmonicTypeMap: Record<string, alphaTab.model.HarmonicType> = {
|
||||
natural: alphaTab.model.HarmonicType.Natural,
|
||||
artificial: alphaTab.model.HarmonicType.Artificial,
|
||||
pinch: alphaTab.model.HarmonicType.Pinch,
|
||||
tap: alphaTab.model.HarmonicType.Tap,
|
||||
semi: alphaTab.model.HarmonicType.Semi,
|
||||
feedback: alphaTab.model.HarmonicType.Feedback
|
||||
};
|
||||
|
||||
/**
|
||||
* Maps a Songsterr tuplet value to an [numerator, denominator] ratio for alphaTab.
|
||||
* E.g., a standard triplet (3) means: play 3 notes in the duration of 2.
|
||||
*
|
||||
* For non-standard/uncommon tuplets, it calculates a reasonable power-of-2 fallback denominator.
|
||||
*
|
||||
* @param tuplet Raw tuplet integer factor from Songsterr.
|
||||
* @returns Tuple representing the tuplet [numerator, denominator].
|
||||
*/
|
||||
function getTupletRatio(tuplet: number): [number, number] {
|
||||
switch (tuplet) {
|
||||
case 3:
|
||||
return [3, 2];
|
||||
case 5:
|
||||
return [5, 4];
|
||||
case 6:
|
||||
return [6, 4];
|
||||
case 7:
|
||||
return [7, 4];
|
||||
case 9:
|
||||
return [9, 8];
|
||||
case 10:
|
||||
return [10, 8];
|
||||
case 12:
|
||||
return [12, 8];
|
||||
default:
|
||||
if (tuplet > 1) {
|
||||
// Find the nearest lower power of 2 as the denominator (e.g., tuplet of 11 -> plays in space of 8)
|
||||
const denominator = Math.pow(2, Math.floor(Math.log2(tuplet)));
|
||||
return [tuplet, denominator];
|
||||
}
|
||||
return [1, 1];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Dynamic mapping generator that constructs a map of MIDI note numbers to alphaTab's default percussion articulation index.
|
||||
*
|
||||
* Guitar Pro format files (GP7) represent percussion/drum articulations not by raw MIDI note values,
|
||||
* but by their index position within the track's percussion articulation array. This function
|
||||
* instantiates a dummy score, exports it to GP7, reimports it, and registers the returned
|
||||
* articulation array order to bypass hardcoded lookup maps.
|
||||
*
|
||||
* @returns Map matching MIDI note numbers to their local zero-indexed drum articulation position.
|
||||
*/
|
||||
function buildPercussionIndexMap(): Map<number, number> {
|
||||
const score = new alphaTab.model.Score();
|
||||
const mb = new alphaTab.model.MasterBar();
|
||||
score.addMasterBar(mb);
|
||||
const track = new alphaTab.model.Track();
|
||||
track.playbackInfo.primaryChannel = 9;
|
||||
track.playbackInfo.secondaryChannel = 9;
|
||||
const staff = new alphaTab.model.Staff();
|
||||
staff.isPercussion = true;
|
||||
track.addStaff(staff);
|
||||
const bar = new alphaTab.model.Bar();
|
||||
const voice = new alphaTab.model.Voice();
|
||||
const beat = new alphaTab.model.Beat();
|
||||
beat.isEmpty = true;
|
||||
voice.addBeat(beat);
|
||||
bar.addVoice(voice);
|
||||
staff.addBar(bar);
|
||||
score.addTrack(track);
|
||||
|
||||
const settings = new alphaTab.Settings();
|
||||
score.finish(settings);
|
||||
const exporter = new alphaTab.exporter.Gp7Exporter();
|
||||
const data = exporter.export(score, settings);
|
||||
const reimported = alphaTab.importer.ScoreLoader.loadScoreFromBytes(
|
||||
data,
|
||||
settings
|
||||
);
|
||||
|
||||
const map = new Map<number, number>();
|
||||
const articulations = reimported.tracks[0].percussionArticulations;
|
||||
for (let i = 0; i < articulations.length; i++) {
|
||||
const id = articulations[i].id;
|
||||
if (!map.has(id)) {
|
||||
map.set(id, i);
|
||||
}
|
||||
}
|
||||
return map;
|
||||
}
|
||||
|
||||
// Singleton cache for the percussion mapping table
|
||||
let percussionIndexMap: Map<number, number> | null = null;
|
||||
|
||||
/**
|
||||
* Retrieves the local Guitar Pro drum articulation index corresponding to a standard MIDI note.
|
||||
*
|
||||
* @param midiNote General MIDI drum note (e.g., 38 for snare, 36 for kick).
|
||||
* @returns Articulation index inside the GP score model.
|
||||
*/
|
||||
function getPercussionArticulationIndex(midiNote: number): number {
|
||||
if (!percussionIndexMap) {
|
||||
percussionIndexMap = buildPercussionIndexMap();
|
||||
}
|
||||
return percussionIndexMap.get(midiNote) ?? midiNote;
|
||||
}
|
||||
|
||||
/**
|
||||
* Core translator class converting rich Songsterr track JSON databases to standard Guitar Pro 7 binary.
|
||||
*/
|
||||
export class SongsterrToAlphaTabConverter {
|
||||
/**
|
||||
* Translates the Songsterr payload into standard Guitar Pro 7 (.gp) binary bytes.
|
||||
*
|
||||
* @param input Collected Songsterr metadata and note payloads.
|
||||
* @returns Binary array representing GP7 file data.
|
||||
*/
|
||||
toGp7(input: SongsterrToGpInput): SongsterrToAlphaTabOutput {
|
||||
const { score, settings, warnings } = this.buildScore(input);
|
||||
|
||||
const exporter = new alphaTab.exporter.Gp7Exporter();
|
||||
const data = exporter.export(score, settings);
|
||||
|
||||
return { data, warnings };
|
||||
}
|
||||
|
||||
/**
|
||||
* Translates the Songsterr payload into a standard MIDI (.mid) file.
|
||||
*
|
||||
* @param input Collected Songsterr metadata and note payloads.
|
||||
* @returns Binary array representing standard MIDI file data.
|
||||
*/
|
||||
toMidi(input: SongsterrToGpInput): SongsterrToAlphaTabOutput {
|
||||
const { score, settings, warnings } = this.buildScore(input);
|
||||
|
||||
const midiFile = new alphaTab.midi.MidiFile();
|
||||
const handler = new alphaTab.midi.AlphaSynthMidiFileHandler(midiFile, true);
|
||||
const generator = new alphaTab.midi.MidiFileGenerator(score, settings, handler);
|
||||
generator.generate();
|
||||
const data = midiFile.toBinary();
|
||||
|
||||
return { data, warnings };
|
||||
}
|
||||
|
||||
/**
|
||||
* Top-down builder compiling alphaTab objects from Songsterr inputs.
|
||||
*/
|
||||
private buildScore({ meta, revisions }: SongsterrToGpInput): BuildScoreResult {
|
||||
const warnings: ConversionWarning[] = [];
|
||||
|
||||
const score = new alphaTab.model.Score();
|
||||
score.title = meta.title;
|
||||
score.artist = meta.artist;
|
||||
score.tab = 'Songsterr Downloader';
|
||||
|
||||
// Locate the longest/most complete track to represent the master timeline baseline
|
||||
const masterTrack = this.pickMasterTrack(revisions);
|
||||
const masterBarCount = Math.max(1, this.getMasterBarCount(revisions));
|
||||
|
||||
// Construct MasterBars representing time signatures, section tags, repeats, and tempo automations
|
||||
this.buildMasterBars({
|
||||
score,
|
||||
masterTrack,
|
||||
masterBarCount,
|
||||
warnings
|
||||
});
|
||||
|
||||
let nextChannel = 0;
|
||||
// Iterate and build individual tracks
|
||||
for (const entry of revisions) {
|
||||
const instrumentId =
|
||||
entry.trackMeta.instrumentId ?? entry.revision.instrumentId;
|
||||
const isPercussion = instrumentId === 1024 || !!entry.trackMeta.isDrums;
|
||||
let channel: number;
|
||||
if (isPercussion) {
|
||||
channel = 9; // Percussion is locked to Channel 9 (MIDI 10)
|
||||
} else {
|
||||
if (nextChannel === 9) nextChannel++; // Skip channel 9 to prevent drum sound bleed on standard instruments
|
||||
channel = nextChannel;
|
||||
nextChannel++;
|
||||
}
|
||||
this.buildTrack({
|
||||
score,
|
||||
entry,
|
||||
masterBarCount,
|
||||
warnings,
|
||||
channel
|
||||
});
|
||||
}
|
||||
|
||||
const settings = new alphaTab.Settings();
|
||||
// Finish compiles the score model and runs checks on bars, voices, and indices
|
||||
score.finish(settings);
|
||||
|
||||
return { score, settings, warnings };
|
||||
}
|
||||
|
||||
/**
|
||||
* Compiles and appends master bars to the global score.
|
||||
* Coordinates global properties like repeats, alternate endings, time signatures, and tempos.
|
||||
*/
|
||||
private buildMasterBars({
|
||||
score,
|
||||
masterTrack,
|
||||
masterBarCount,
|
||||
warnings
|
||||
}: {
|
||||
score: alphaTab.model.Score;
|
||||
masterTrack: SongsterrRevisionTrackPayload | null;
|
||||
masterBarCount: number;
|
||||
warnings: ConversionWarning[];
|
||||
}): void {
|
||||
let timeSignatureNumerator = 4;
|
||||
let timeSignatureDenominator = 4;
|
||||
|
||||
for (let index = 0; index < masterBarCount; index++) {
|
||||
const measure = masterTrack?.measures?.[index];
|
||||
const signature = this.getValidSignature(measure?.signature);
|
||||
// Propagate time signature changes down the timeline
|
||||
if (signature) {
|
||||
[timeSignatureNumerator, timeSignatureDenominator] = signature;
|
||||
}
|
||||
|
||||
const masterBar = new alphaTab.model.MasterBar();
|
||||
masterBar.timeSignatureNumerator = timeSignatureNumerator;
|
||||
masterBar.timeSignatureDenominator = timeSignatureDenominator;
|
||||
|
||||
// Extract section markers ("Intro", "Verse", "Chorus", etc.)
|
||||
if (measure?.marker) {
|
||||
const section = new alphaTab.model.Section();
|
||||
const markerText = this.extractMarkerText(measure.marker);
|
||||
section.marker = markerText;
|
||||
section.text = markerText;
|
||||
masterBar.section = section;
|
||||
}
|
||||
|
||||
// Handle Repeat bracket structures
|
||||
if (measure?.repeatStart) {
|
||||
masterBar.isRepeatStart = true;
|
||||
}
|
||||
|
||||
if (typeof measure?.repeatCount === 'number' && measure.repeatCount > 0) {
|
||||
masterBar.repeatCount = measure.repeatCount;
|
||||
}
|
||||
|
||||
// Handle alternate endings (e.g., 1st ending, 2nd ending)
|
||||
if (
|
||||
typeof measure?.alternateEnding === 'number' &&
|
||||
measure.alternateEnding > 0
|
||||
) {
|
||||
masterBar.alternateEndings = measure.alternateEnding;
|
||||
}
|
||||
|
||||
score.addMasterBar(masterBar);
|
||||
}
|
||||
|
||||
// Process global tempo changes
|
||||
const tempoPoints = this.findTempoPoints(masterTrack);
|
||||
this.applyTempoAutomations(score, tempoPoints, warnings);
|
||||
}
|
||||
|
||||
/**
|
||||
* Constructs an individual track (instrument voice), populates it with bars,
|
||||
* scans and formats voice dimensions, and attaches it to the score.
|
||||
*/
|
||||
private buildTrack({
|
||||
score,
|
||||
entry,
|
||||
masterBarCount,
|
||||
warnings,
|
||||
channel
|
||||
}: {
|
||||
score: alphaTab.model.Score;
|
||||
entry: SongsterrRevisionTrackInput;
|
||||
masterBarCount: number;
|
||||
warnings: ConversionWarning[];
|
||||
channel: number;
|
||||
}): void {
|
||||
const { trackMeta, revision } = entry;
|
||||
const playbackMapping = mapSongsterrInstrumentToPlayback(
|
||||
trackMeta.instrumentId ?? revision.instrumentId
|
||||
);
|
||||
|
||||
const track = new alphaTab.model.Track();
|
||||
track.name = trackMeta.title || trackMeta.name || revision.name || 'Track';
|
||||
track.shortName = track.name.slice(0, 20);
|
||||
track.playbackInfo.program = playbackMapping.program;
|
||||
track.playbackInfo.primaryChannel = channel;
|
||||
track.playbackInfo.secondaryChannel = channel;
|
||||
|
||||
const staff = new alphaTab.model.Staff();
|
||||
const tuning = revision.tuning || trackMeta.tuning;
|
||||
if (Array.isArray(tuning) && tuning.length > 0) {
|
||||
staff.stringTuning = new alphaTab.model.Tuning('Custom', tuning, false);
|
||||
}
|
||||
const isPercussion = playbackMapping.isPercussion || !!trackMeta.isDrums;
|
||||
staff.isPercussion = isPercussion;
|
||||
const numStrings = Array.isArray(tuning) ? tuning.length : 6;
|
||||
|
||||
// CRITICAL BUG PREVENTION: Pre-scan to determine the maximum voice count across all measures.
|
||||
// alphaTab expects every single bar in a staff to have the same number of voices.
|
||||
// If a measure has 2 voices (e.g., fingerstyle melody + bassline) but a neighbouring measure only
|
||||
// has 1, the compiler will crash inside Voice._chain when calling score.finish().
|
||||
// We pad shorter measures with empty rest voices to match the maximum.
|
||||
let maxVoiceCount = 1;
|
||||
for (let i = 0; i < masterBarCount; i++) {
|
||||
const m = revision.measures?.[i];
|
||||
maxVoiceCount = Math.max(maxVoiceCount, m?.voices?.length || 0);
|
||||
}
|
||||
|
||||
for (let measureIndex = 0; measureIndex < masterBarCount; measureIndex++) {
|
||||
const bar = new alphaTab.model.Bar();
|
||||
const measure = revision.measures?.[measureIndex];
|
||||
const voiceCount = measure?.voices?.length || 0;
|
||||
|
||||
if (voiceCount === 0) {
|
||||
// Empty measure: pad with a single rest voice populated with silent beats
|
||||
const voice = new alphaTab.model.Voice();
|
||||
this.fillWithRestBeats(voice, score.masterBars[measureIndex]);
|
||||
bar.addVoice(voice);
|
||||
} else {
|
||||
// Process and append all voices
|
||||
for (let voiceIndex = 0; voiceIndex < voiceCount; voiceIndex++) {
|
||||
const voice = new alphaTab.model.Voice();
|
||||
const sourceVoice = measure!.voices![voiceIndex];
|
||||
|
||||
this.fillVoice({
|
||||
voice,
|
||||
sourceVoice,
|
||||
masterBar: score.masterBars[measureIndex],
|
||||
warnings,
|
||||
locationPrefix: `track:${trackMeta.partId}|measure:${measureIndex}|voice:${voiceIndex}`,
|
||||
isPercussion,
|
||||
numStrings
|
||||
});
|
||||
|
||||
bar.addVoice(voice);
|
||||
}
|
||||
}
|
||||
|
||||
// Pad remaining empty slots with silent rest voices to match maxVoiceCount
|
||||
for (let v = bar.voices.length; v < maxVoiceCount; v++) {
|
||||
const restVoice = new alphaTab.model.Voice();
|
||||
this.fillWithRestBeats(restVoice, score.masterBars[measureIndex]);
|
||||
bar.addVoice(restVoice);
|
||||
}
|
||||
|
||||
staff.addBar(bar);
|
||||
}
|
||||
|
||||
track.addStaff(staff);
|
||||
score.addTrack(track);
|
||||
}
|
||||
|
||||
/**
|
||||
* Fills an alphaTab Voice with translated beats parsed from a Songsterr Voice payload.
|
||||
*/
|
||||
private fillVoice({
|
||||
voice,
|
||||
sourceVoice,
|
||||
masterBar,
|
||||
warnings,
|
||||
locationPrefix,
|
||||
isPercussion,
|
||||
numStrings
|
||||
}: {
|
||||
voice: alphaTab.model.Voice;
|
||||
sourceVoice: SongsterrRevisionVoicePayload | undefined;
|
||||
masterBar: alphaTab.model.MasterBar;
|
||||
warnings: ConversionWarning[];
|
||||
locationPrefix: string;
|
||||
isPercussion: boolean;
|
||||
numStrings: number;
|
||||
}): void {
|
||||
const beats = sourceVoice?.beats || [];
|
||||
|
||||
// Fallback if the voice is entirely silent
|
||||
if (beats.length === 0 || sourceVoice?.rest) {
|
||||
this.fillWithRestBeats(voice, masterBar);
|
||||
return;
|
||||
}
|
||||
|
||||
for (let beatIndex = 0; beatIndex < beats.length; beatIndex++) {
|
||||
const beatData = beats[beatIndex];
|
||||
const beat = this.mapBeat(
|
||||
beatData,
|
||||
warnings,
|
||||
`${locationPrefix}|beat:${beatIndex}`,
|
||||
isPercussion,
|
||||
numStrings
|
||||
);
|
||||
voice.addBeat(beat);
|
||||
}
|
||||
|
||||
if (voice.beats.length === 0) {
|
||||
this.fillWithRestBeats(voice, masterBar);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Maps detailed musical beat information (tuplets, lyrics/texts, pick strokes, velocities, dynamics) to alphaTab models.
|
||||
*/
|
||||
private mapBeat(
|
||||
beatData: SongsterrRevisionBeatPayload,
|
||||
warnings: ConversionWarning[],
|
||||
location: string,
|
||||
isPercussion: boolean,
|
||||
numStrings: number
|
||||
): alphaTab.model.Beat {
|
||||
const beat = new alphaTab.model.Beat();
|
||||
|
||||
// Mark rest beats
|
||||
if (beatData.rest) {
|
||||
beat.isEmpty = true;
|
||||
}
|
||||
|
||||
// Convert duration structure
|
||||
const mappedDuration = mapSongsterrDuration(beatData.duration);
|
||||
beat.duration = mappedDuration.duration;
|
||||
beat.dots = beatData.dots ?? mappedDuration.dots;
|
||||
const rawText = beatData.text;
|
||||
const textStr = typeof rawText === 'string' ? rawText : rawText?.text;
|
||||
beat.text = (textStr as string | undefined) || null;
|
||||
|
||||
if (mappedDuration.isApproximate && !beatData.tuplet) {
|
||||
this.pushWarning(warnings, {
|
||||
code: 'duration_approximated',
|
||||
message: `Approximated unsupported duration ${JSON.stringify(
|
||||
beatData.duration
|
||||
)}`,
|
||||
location
|
||||
});
|
||||
}
|
||||
|
||||
// Process tuplets (e.g., triplets, quintuplets, etc.)
|
||||
if (typeof beatData.tuplet === 'number' && beatData.tuplet > 1) {
|
||||
const [num, den] = getTupletRatio(beatData.tuplet);
|
||||
beat.tupletNumerator = num;
|
||||
beat.tupletDenominator = den;
|
||||
|
||||
// When mapping a tuplet, the underlying duration should match the base time value
|
||||
// of the notes, as the tuplet fraction itself modifies the duration.
|
||||
if (typeof beatData.type === 'number' && beatData.type > 0) {
|
||||
const baseDuration = mapSongsterrDuration([1, beatData.type]);
|
||||
beat.duration = baseDuration.duration;
|
||||
beat.dots = beatData.dots ?? 0;
|
||||
}
|
||||
}
|
||||
|
||||
// Apply MIDI velocity values to dynamics
|
||||
if (typeof beatData.velocity === 'string') {
|
||||
const mappedDynamic =
|
||||
velocityToDynamicMap[beatData.velocity.toLowerCase()];
|
||||
if (typeof mappedDynamic === 'number') {
|
||||
beat.dynamics = mappedDynamic;
|
||||
} else {
|
||||
this.pushWarning(warnings, {
|
||||
code: 'velocity_unknown',
|
||||
message: `Unsupported beat velocity "${beatData.velocity}"`,
|
||||
location
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Map pick stroke directions
|
||||
if (typeof beatData.pickStroke === 'string') {
|
||||
const ps = beatData.pickStroke.toLowerCase();
|
||||
if (ps === 'down') {
|
||||
beat.pickStroke = alphaTab.model.PickStroke.Down;
|
||||
} else if (ps === 'up') {
|
||||
beat.pickStroke = alphaTab.model.PickStroke.Up;
|
||||
}
|
||||
}
|
||||
|
||||
// Map beat-level vibratos
|
||||
if (beatData.wideVibrato || beatData.vibratoWithTremoloBar) {
|
||||
beat.vibrato = alphaTab.model.VibratoType.Wide;
|
||||
} else if (beatData.vibrato) {
|
||||
beat.vibrato = alphaTab.model.VibratoType.Slight;
|
||||
}
|
||||
|
||||
// Iterate notes present on this beat
|
||||
const notes = beatData.notes || [];
|
||||
for (let noteIndex = 0; noteIndex < notes.length; noteIndex++) {
|
||||
const noteData = notes[noteIndex];
|
||||
if (noteData.rest) {
|
||||
continue;
|
||||
}
|
||||
const note = this.mapNote(
|
||||
noteData,
|
||||
beatData,
|
||||
warnings,
|
||||
`${location}|note:${noteIndex}`,
|
||||
isPercussion,
|
||||
numStrings
|
||||
);
|
||||
beat.addNote(note);
|
||||
}
|
||||
|
||||
return beat;
|
||||
}
|
||||
|
||||
/**
|
||||
* Maps a single note and its underlying technical performance properties
|
||||
* (ties, dead/muted notes, ghost notes, legato hammer-ons/pull-offs, slides, harmonics, bends) to alphaTab models.
|
||||
*/
|
||||
private mapNote(
|
||||
noteData: SongsterrRevisionNotePayload,
|
||||
beatData: SongsterrRevisionBeatPayload,
|
||||
warnings: ConversionWarning[],
|
||||
location: string,
|
||||
isPercussion: boolean,
|
||||
numStrings: number
|
||||
): alphaTab.model.Note {
|
||||
const note = new alphaTab.model.Note();
|
||||
|
||||
// STRING MAPPING:
|
||||
// Songsterr: 0 = highest pitch string.
|
||||
// alphaTab: 1 = lowest pitch string.
|
||||
// Thus we invert the string index: string = totalStrings - songsterrString
|
||||
note.string = isPercussion ? -1 : numStrings - (noteData.string ?? 0);
|
||||
note.fret = noteData.fret ?? 0;
|
||||
|
||||
// Set percussion articulation reference if this is a drum track
|
||||
if (isPercussion) {
|
||||
note.percussionArticulation = getPercussionArticulationIndex(
|
||||
noteData.fret ?? 0
|
||||
);
|
||||
}
|
||||
|
||||
// Tie notes together
|
||||
if (noteData.tie) {
|
||||
note.isTieDestination = true;
|
||||
}
|
||||
|
||||
// Dead / muted notes
|
||||
if (noteData.dead) {
|
||||
note.isDead = true;
|
||||
}
|
||||
|
||||
// Ghost (bracketed/soft) notes
|
||||
if (noteData.ghost) {
|
||||
note.isGhost = true;
|
||||
}
|
||||
|
||||
// Hammer-on or pull-off (legato transition)
|
||||
if (noteData.hp) {
|
||||
note.isHammerPullOrigin = true;
|
||||
}
|
||||
|
||||
// Staccato articulation
|
||||
if (noteData.staccato) {
|
||||
note.isStaccato = true;
|
||||
}
|
||||
|
||||
// Accentuated articulation
|
||||
if (noteData.accentuated) {
|
||||
note.accentuated = alphaTab.model.AccentuationType.Normal;
|
||||
}
|
||||
|
||||
// Palm muting (inherited from the parent beat level)
|
||||
if (beatData.palmMute) {
|
||||
note.isPalmMute = true;
|
||||
}
|
||||
|
||||
// Note-level pitch vibrato (takes priority over beat level)
|
||||
if (noteData.wideVibrato) {
|
||||
note.vibrato = alphaTab.model.VibratoType.Wide;
|
||||
} else if (noteData.vibrato) {
|
||||
note.vibrato = alphaTab.model.VibratoType.Slight;
|
||||
}
|
||||
|
||||
// Slide effects (legato, shift, slide in, slide out)
|
||||
if (typeof noteData.slide === 'string') {
|
||||
this.mapSlide(note, noteData.slide, warnings, location);
|
||||
}
|
||||
|
||||
// Harmonics (natural, artificial, pinch, tap, feedback)
|
||||
if (typeof noteData.harmonic === 'string') {
|
||||
this.mapHarmonic(note, noteData, warnings, location);
|
||||
}
|
||||
|
||||
// Pitch bends
|
||||
if (noteData.bend && noteData.bend.points && noteData.bend.points.length > 0) {
|
||||
this.mapBend(note, noteData.bend);
|
||||
}
|
||||
|
||||
return note;
|
||||
}
|
||||
|
||||
/**
|
||||
* Maps Songsterr slide terms to alphaTab's input and output slide types.
|
||||
*/
|
||||
private mapSlide(
|
||||
note: alphaTab.model.Note,
|
||||
slide: string,
|
||||
warnings: ConversionWarning[],
|
||||
location: string
|
||||
): void {
|
||||
const normalizedSlide = slide.toLowerCase();
|
||||
if (normalizedSlide === 'shift') {
|
||||
note.slideOutType = alphaTab.model.SlideOutType.Shift;
|
||||
return;
|
||||
}
|
||||
if (normalizedSlide === 'legato') {
|
||||
note.slideOutType = alphaTab.model.SlideOutType.Legato;
|
||||
return;
|
||||
}
|
||||
if (normalizedSlide === 'into_from_below' || normalizedSlide === 'below') {
|
||||
note.slideInType = alphaTab.model.SlideInType.IntoFromBelow;
|
||||
return;
|
||||
}
|
||||
if (normalizedSlide === 'into_from_above') {
|
||||
note.slideInType = alphaTab.model.SlideInType.IntoFromAbove;
|
||||
return;
|
||||
}
|
||||
if (normalizedSlide === 'out_up') {
|
||||
note.slideOutType = alphaTab.model.SlideOutType.OutUp;
|
||||
return;
|
||||
}
|
||||
if (normalizedSlide === 'out_down' || normalizedSlide === 'downwards') {
|
||||
note.slideOutType = alphaTab.model.SlideOutType.OutDown;
|
||||
return;
|
||||
}
|
||||
|
||||
this.pushWarning(warnings, {
|
||||
code: 'slide_unsupported',
|
||||
message: `Unsupported slide effect "${slide}"`,
|
||||
location
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Maps Songsterr harmonic terms to alphaTab's harmonic types and sets the harmonic center fret.
|
||||
*/
|
||||
private mapHarmonic(
|
||||
note: alphaTab.model.Note,
|
||||
noteData: SongsterrRevisionNotePayload,
|
||||
warnings: ConversionWarning[],
|
||||
location: string
|
||||
): void {
|
||||
const harmonicStr = noteData.harmonic!.toLowerCase();
|
||||
const mappedType = harmonicTypeMap[harmonicStr];
|
||||
|
||||
if (typeof mappedType === 'number') {
|
||||
note.harmonicType = mappedType;
|
||||
if (typeof noteData.harmonicFret === 'number') {
|
||||
note.harmonicValue = noteData.harmonicFret;
|
||||
}
|
||||
} else {
|
||||
this.pushWarning(warnings, {
|
||||
code: 'harmonic_unsupported',
|
||||
message: `Unsupported harmonic type "${noteData.harmonic}"`,
|
||||
location
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Maps Songsterr bend vectors to alphaTab BendPoints.
|
||||
*
|
||||
* FORMULA DETAILS:
|
||||
* - Songsterr coordinates: position ranges from 0 to 60.
|
||||
* - Guitar Pro and Songsterr scale: 100 pitch units = 1 full tone (2 semitones). 50 units = 1 semitone.
|
||||
* - alphaTab BendPoint.value expects quarter-steps (where 25 GP units = 1 unit, MaxValue = 12, matching 3 full tones).
|
||||
* - Conversion: alphaTab_value = Songsterr_tone / 25
|
||||
*/
|
||||
private mapBend(
|
||||
note: alphaTab.model.Note,
|
||||
bend: { tone: number; points: { position: number; tone: number }[] }
|
||||
): void {
|
||||
note.bendType = alphaTab.model.BendType.Custom;
|
||||
|
||||
for (const point of bend.points) {
|
||||
const offset = Math.round(point.position);
|
||||
const value = Math.round(point.tone / 25);
|
||||
note.addBendPoint(new alphaTab.model.BendPoint(offset, value));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fills an empty voice with a string of silent rest beats matching the time signature dimensions of the MasterBar.
|
||||
*/
|
||||
private fillWithRestBeats(
|
||||
voice: alphaTab.model.Voice,
|
||||
masterBar: alphaTab.model.MasterBar
|
||||
): void {
|
||||
const denominator = masterBar.timeSignatureDenominator || 4;
|
||||
const numerator = masterBar.timeSignatureNumerator || 4;
|
||||
|
||||
const mappedDuration = mapSongsterrDuration([1, denominator]);
|
||||
for (let i = 0; i < numerator; i++) {
|
||||
const restBeat = new alphaTab.model.Beat();
|
||||
restBeat.isEmpty = true;
|
||||
restBeat.duration = mappedDuration.duration;
|
||||
restBeat.dots = mappedDuration.dots;
|
||||
voice.addBeat(restBeat);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Scans and returns the highest measure count found across all track revisions.
|
||||
*/
|
||||
private getMasterBarCount(revisions: SongsterrRevisionTrackInput[]): number {
|
||||
return revisions.reduce((max, entry) => {
|
||||
return Math.max(max, entry.revision?.measures?.length || 0);
|
||||
}, 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* Identifies the track revision containing the largest number of measures to use as the master sync track.
|
||||
*/
|
||||
private pickMasterTrack(
|
||||
revisions: SongsterrRevisionTrackInput[]
|
||||
): SongsterrRevisionTrackPayload | null {
|
||||
if (revisions.length === 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return revisions.reduce((longest, current) => {
|
||||
const currentLength = current.revision?.measures?.length || 0;
|
||||
const longestLength = longest.revision?.measures?.length || 0;
|
||||
return currentLength > longestLength ? current : longest;
|
||||
}).revision;
|
||||
}
|
||||
|
||||
/**
|
||||
* Helper verifying if a time signature array is complete and valid.
|
||||
*/
|
||||
private getValidSignature(
|
||||
signature: [number, number] | undefined
|
||||
): [number, number] | null {
|
||||
if (!Array.isArray(signature) || signature.length !== 2) {
|
||||
return null;
|
||||
}
|
||||
const [numerator, denominator] = signature;
|
||||
if (!numerator || !denominator) {
|
||||
return null;
|
||||
}
|
||||
return [numerator, denominator];
|
||||
}
|
||||
|
||||
/**
|
||||
* Helper extracting clean text from complex marker payloads.
|
||||
*/
|
||||
private extractMarkerText(marker: string | { text: string; width?: number }): string {
|
||||
if (typeof marker === 'string') {
|
||||
return marker;
|
||||
}
|
||||
if (marker && typeof marker === 'object' && typeof marker.text === 'string') {
|
||||
return marker.text;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts tempo change points defined in the track revision.
|
||||
*/
|
||||
private findTempoPoints(
|
||||
masterTrack: SongsterrRevisionTrackPayload | null
|
||||
): SongsterrRevisionAutomationTempoPoint[] {
|
||||
const tempo = masterTrack?.automations?.tempo;
|
||||
return Array.isArray(tempo) ? tempo : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Applies tempo automation objects to the corresponding MasterBars in the score.
|
||||
*/
|
||||
private applyTempoAutomations(
|
||||
score: alphaTab.model.Score,
|
||||
points: SongsterrRevisionAutomationTempoPoint[],
|
||||
warnings: ConversionWarning[]
|
||||
): void {
|
||||
for (const point of points) {
|
||||
const barIndex = point.measure;
|
||||
const masterBar = score.masterBars[barIndex];
|
||||
if (!masterBar) {
|
||||
this.pushWarning(warnings, {
|
||||
code: 'tempo_measure_out_of_range',
|
||||
message: `Tempo automation references missing measure ${barIndex}`,
|
||||
location: `measure:${barIndex}`
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
// alphaTab reference indices: 0=whole, 1=half(×0.5), 2=quarter(×1.0), 3=dotted-quarter(×1.5), 4=half(×2.0), 5=dotted-half(×3.0)
|
||||
// Since Songsterr's BPM is always based on quarter notes, we use reference 2.
|
||||
const tempoReference = 2;
|
||||
const ratioPosition =
|
||||
point.position > 0
|
||||
? Math.max(0, Math.min(1, point.position / (point.type || 4)))
|
||||
: 0;
|
||||
const tempoAutomation = alphaTab.model.Automation.buildTempoAutomation(
|
||||
false,
|
||||
ratioPosition,
|
||||
point.bpm,
|
||||
tempoReference,
|
||||
true
|
||||
);
|
||||
masterBar.tempoAutomations.push(tempoAutomation);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Appends a conversion warning if the threshold limit has not been reached.
|
||||
*/
|
||||
private pushWarning(
|
||||
warnings: ConversionWarning[],
|
||||
warning: ConversionWarning
|
||||
): void {
|
||||
if (warnings.length < MAX_WARNINGS) {
|
||||
warnings.push(warning);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user