@hymnbook/abc 0.0.1 → 0.2.0

package/dist/{index.mjs → index.cjs}

@@ -1,4 +1,52 @@
-// src/abcTypes.ts
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AbcSong: () => AbcSong,
+  ValidationError: () => ValidationError,
+  addInfoFieldsToMelody: () => addInfoFieldsToMelody,
+  combineMelodyAndLyrics: () => combineMelodyAndLyrics,
+  convertStringToAbcTune: () => convertStringToAbcTune,
+  extractInfoFields: () => extractInfoFields,
+  generateAbcForVerse: () => generateAbcForVerse,
+  getField: () => getField,
+  getForVerse: () => getForVerse,
+  parse: () => parse,
+  squashNotesAndLyrics: () => squashNotesAndLyrics,
+  stringify: () => stringify,
+  validate: () => validate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
 var AbcSong = class {
   // See also: https://abcnotation.com/wiki/abc:standard:v2.1#information_fields
   area;
@@ -40,8 +88,8 @@ var AbcSong = class {
   };
 };
 
-// src/abc.ts
-import * as ABCJS from "abcjs";
+// src/parser.ts
+var ABCJS = __toESM(require("abcjs"), 1);
 
 // src/validation.ts
 var ValidationError = class extends Error {
@@ -53,15 +101,155 @@ function validate(result, message) {
   throw new ValidationError(message || "Value is not true");
 }
 
-// src/abc.ts
+// src/deparser.ts
+var addInfoFieldsToMelody = (song, abc) => {
+  let result = "";
+  result += song.referenceNumber === void 0 ? "" : "X:" + song.referenceNumber + "\n";
+  result += song.title === void 0 ? "" : "T:" + song.title + "\n";
+  result += song.area === void 0 ? "" : "A:" + song.area + "\n";
+  result += song.book === void 0 ? "" : "B:" + song.book + "\n";
+  result += song.composer === void 0 ? "" : "C:" + song.composer + "\n";
+  result += song.discography === void 0 ? "" : "D:" + song.discography + "\n";
+  result += song.fileUrl === void 0 ? "" : "F:" + song.fileUrl + "\n";
+  result += song.group === void 0 ? "" : "G:" + song.group + "\n";
+  result += song.history === void 0 ? "" : "H:" + song.history + "\n";
+  result += song.instruction === void 0 ? "" : "I:" + song.instruction + "\n";
+  result += song.key === void 0 ? "" : "K:" + song.key + "\n";
+  result += song.unitNoteLength === void 0 ? "" : "L:" + song.unitNoteLength + "\n";
+  result += song.meter === void 0 ? "" : "M:" + song.meter + "\n";
+  result += song.macro === void 0 ? "" : "m:" + song.macro + "\n";
+  result += song.notes === void 0 ? "" : "N:" + song.notes + "\n";
+  result += song.origin === void 0 ? "" : "O:" + song.origin + "\n";
+  result += song.parts === void 0 ? "" : "P:" + song.parts + "\n";
+  result += song.tempo === void 0 ? "" : "Q:" + song.tempo + "\n";
+  result += song.rhythm === void 0 ? "" : "R:" + song.rhythm + "\n";
+  result += song.remark === void 0 ? "" : "r:" + song.remark + "\n";
+  result += song.source === void 0 ? "" : "S:" + song.source + "\n";
+  result += song.symbolLine === void 0 ? "" : "s:" + song.symbolLine + "\n";
+  result += song.userDefined === void 0 ? "" : "U:" + song.userDefined + "\n";
+  result += song.voice === void 0 ? "" : "V:" + song.voice + "\n";
+  result += song.transcription === void 0 ? "" : "Z:" + song.transcription + "\n";
+  return result + abc;
+};
+var durationToString = (duration) => {
+  duration /= 4;
+  if (duration > 3 / 8) return (duration * 4).toString();
+  if (duration == 1 / 4) return "";
+  if (duration == 3 / 8) return "3/2";
+  if (duration == 1 / 8) return "/2";
+  if (duration == 3 / 16) return "3/4";
+  if (duration == 1 / 16) return "/4";
+  if (duration == 3 / 32) return "3/8";
+  if (duration == 1 / 32) return "/8";
+  if (duration == 3 / 64) return "3/16";
+  return "";
+};
+var voiceBarToString = (voice) => {
+  let result = "";
+  switch (voice.type) {
+    case "bar_thin":
+      result += "|";
+      break;
+    case "bar_thin_thick":
+      result += "|]";
+      break;
+    case "bar_thin_thin":
+      result += "||";
+      break;
+    case "bar_thick_thin":
+      result += "[|";
+      break;
+    case "bar_right_repeat":
+      result += ":|";
+      break;
+    case "bar_left_repeat":
+      result += "|:";
+      break;
+    case "bar_dbl_repeat":
+      result += "::";
+      break;
+  }
+  if (voice.startEnding) result += voice.startEnding;
+  return result + " ";
+};
+var voiceNoteToString = (voice, durationMultiplier, isBeam) => {
+  let notes = "";
+  let lyrics = "";
+  const duration = durationToString(voice.duration / durationMultiplier);
+  if (voice.startBeam) isBeam = true;
+  if (voice.endBeam) isBeam = false;
+  voice.chord?.forEach((chord) => {
+    const parsedChordName = chord.name.replaceAll(/♭/g, "b").replaceAll(/♯/g, "#");
+    notes += `"${parsedChordName}"`;
+  });
+  if (voice.pitches && voice.pitches?.length > 1) notes += "[";
+  voice.pitches?.forEach((pitch) => {
+    let note = pitch.name + duration;
+    if (pitch.startSlur) note = "(".repeat(pitch.startSlur.length) + note;
+    if (pitch.endSlur) note += ")".repeat(pitch.endSlur.length);
+    if (pitch.startTie) note += "-";
+    notes += note;
+  });
+  if (voice.pitches && voice.pitches?.length > 1) notes += "]";
+  if (voice.rest) {
+    if (voice.rest.type == "spacer") {
+      notes += "y";
+    } else if (voice.rest.type == "multimeasure") {
+      notes += "Z" + durationToString(voice.duration / 4);
+    } else {
+      notes += "z" + duration;
+    }
+  }
+  if (voice.pitches) {
+    voice.lyric?.forEach((lyric) => {
+      let text = lyric.syllable.replace(/ /g, "~");
+      if (text == "") text = "*";
+      lyrics += text + lyric.divider;
+    });
+  }
+  if (!isBeam) notes += " ";
+  return {
+    notes,
+    lyrics,
+    isBeam
+  };
+};
+var stringify = (song) => {
+  const durationParts = (song.unitNoteLength || "1/8").split("/");
+  const durationMultiplier = durationParts.length > 1 ? +durationParts[0] / +durationParts[1] : +durationParts[0];
+  const melody = song.melody.flatMap((line) => {
+    const notes = [];
+    const lyrics = [];
+    let isBeam = false;
+    line.forEach((voice) => {
+      switch (voice.el_type) {
+        case "bar":
+          notes.push(voiceBarToString(voice));
+          break;
+        case "note":
+          const result2 = voiceNoteToString(voice, durationMultiplier, isBeam);
+          notes.push(result2.notes);
+          lyrics.push(result2.lyrics);
+          isBeam = result2.isBeam;
+          break;
+      }
+    });
+    const result = [notes.join("").trim()];
+    const mergedLyrics = lyrics.join("").trim();
+    if (mergedLyrics.length > 0) {
+      result.push("w: " + mergedLyrics);
+    }
+    return result;
+  }).join("\n");
+  return addInfoFieldsToMelody(song, melody);
+};
+
+// src/parser.ts
 var parse = (abc) => {
   abc = abc.replace(/%.*/g, "").replaceAll(/\n+/g, "\n");
   const song = new AbcSong();
   extractInfoFields(abc, song);
   const tuneObject = convertStringToAbcTune(abc);
-  if (tuneObject === void 0) {
-    return void 0;
-  }
   song.clef = tuneObject.lines[0].staff[0].clef || song.clef;
   song.keySignature = tuneObject.lines[0].staff[0].key || song.keySignature;
   song.melody = tuneObject.lines.map((line) => line.staff[0].voices[0]);
@@ -149,7 +337,7 @@ var extractInfoFields = (abc, song) => {
   song.transcription = getField(abc, "Z");
   return abc.replace(/%.*\n/g, "").replace(/(^|\n) *\t*[ABCDFGHIKLMmNOPQRrSsTUVXZ]:.*/g, "").replace(/\n+/g, "\n").replace(/^\n*/g, "").replace(/\n*$/g, "");
 };
-var extractNotesAndLyrics = (abc) => {
+var squashNotesAndLyrics = (abc) => {
   const notes = [];
   const lyrics = [];
   abc.split("\n").map((it) => it.trim()).forEach((it) => {
@@ -164,41 +352,13 @@ var extractNotesAndLyrics = (abc) => {
     lyrics: lyrics.join(" ")
   };
 };
-var addInfoFieldsToMelody = (song, abc) => {
-  let result = "";
-  result += song.referenceNumber === void 0 ? "" : "X:" + song.referenceNumber + "\n";
-  result += song.title === void 0 ? "" : "T:" + song.title + "\n";
-  result += song.area === void 0 ? "" : "A:" + song.area + "\n";
-  result += song.book === void 0 ? "" : "B:" + song.book + "\n";
-  result += song.composer === void 0 ? "" : "C:" + song.composer + "\n";
-  result += song.discography === void 0 ? "" : "D:" + song.discography + "\n";
-  result += song.fileUrl === void 0 ? "" : "F:" + song.fileUrl + "\n";
-  result += song.group === void 0 ? "" : "G:" + song.group + "\n";
-  result += song.history === void 0 ? "" : "H:" + song.history + "\n";
-  result += song.instruction === void 0 ? "" : "I:" + song.instruction + "\n";
-  result += song.key === void 0 ? "" : "K:" + song.key + "\n";
-  result += song.unitNoteLength === void 0 ? "" : "L:" + song.unitNoteLength + "\n";
-  result += song.meter === void 0 ? "" : "M:" + song.meter + "\n";
-  result += song.macro === void 0 ? "" : "m:" + song.macro + "\n";
-  result += song.notes === void 0 ? "" : "N:" + song.notes + "\n";
-  result += song.origin === void 0 ? "" : "O:" + song.origin + "\n";
-  result += song.parts === void 0 ? "" : "P:" + song.parts + "\n";
-  result += song.tempo === void 0 ? "" : "Q:" + song.tempo + "\n";
-  result += song.rhythm === void 0 ? "" : "R:" + song.rhythm + "\n";
-  result += song.remark === void 0 ? "" : "r:" + song.remark + "\n";
-  result += song.source === void 0 ? "" : "S:" + song.source + "\n";
-  result += song.symbolLine === void 0 ? "" : "s:" + song.symbolLine + "\n";
-  result += song.userDefined === void 0 ? "" : "U:" + song.userDefined + "\n";
-  result += song.voice === void 0 ? "" : "V:" + song.voice + "\n";
-  result += song.transcription === void 0 ? "" : "Z:" + song.transcription + "\n";
-  return result + abc;
-};
 var convertStringToAbcTune = (abc) => {
   const objectArray = ABCJS.parseOnly(abc);
   const object = objectArray;
   validate(object != null, "Tune object may not be null");
   validate(object.length > 0, "Tune object may not be empty");
   validate(object[0].lines != null, "Tune object lines may not be null");
+  object[0].lines = object[0].lines.filter((it) => it.staff);
   validate(object[0].lines.length > 0, "Tune object lines are empty");
   validate(object[0].lines[0].staff != null, "Staffs may not be null");
   validate(object[0].lines[0].staff.length > 0, "Staffs are empty");
@@ -221,10 +381,10 @@ var processAbcLyrics = (object) => {
     )
   );
 };
-var combineMelodyAndLyrics = (melody, lyrics) => {
+var combineMelodyAndLyrics = (melody, lyrics, options = { trimLines: false }) => {
   const song = new AbcSong();
   const rawMelody = extractInfoFields(melody, song);
-  const melodyLines = rawMelody.replaceAll(/\n+/g, "\n").trim().split("\n");
+  const melodyLines = rawMelody.replaceAll(/\n+/g, "\n").trim().split("\n").map((it) => it.trim()).map((it) => options.trimLines ? it.replaceAll(/(^y+|y+$)*/gi, "").replaceAll(/ *y* *(\|+]*) *y* */gi, " $1 ").trim() : it);
   const lyricLines = lyrics.replaceAll(/\n+/g, "\n").trim().split("\n");
   const mixedMelody = [];
   for (let i = 0; i < Math.max(melodyLines.length, lyricLines.length); i++) {
@@ -239,24 +399,26 @@ var getForVerse = (melody, verse) => melody.subMelodies.find((it) => (
   // `.includes()` won't work due to the Realm data type of `verseUuids`.
   it.verseUuids.some((it2) => it2 == verse.uuid)
 ));
-var generateAbcForVerse = (verse, activeMelody) => {
+var generateAbcForVerse = (verse, activeMelody, options = { trimLines: false }) => {
   if (activeMelody === void 0) {
     return "";
   }
   const melody = getForVerse(activeMelody, verse)?.melody || activeMelody.melody;
-  return combineMelodyAndLyrics(melody, verse.abcLyrics || "");
+  return combineMelodyAndLyrics(melody, verse.abcLyrics || "", options);
 };
-export {
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
   AbcSong,
   ValidationError,
   addInfoFieldsToMelody,
   combineMelodyAndLyrics,
   convertStringToAbcTune,
   extractInfoFields,
-  extractNotesAndLyrics,
   generateAbcForVerse,
   getField,
   getForVerse,
   parse,
+  squashNotesAndLyrics,
+  stringify,
   validate
-};
+});

package/dist/{index.d.mts → index.d.cts}

@@ -3,7 +3,7 @@ import { SynthOptions } from 'abcjs';
 type AccidentalName = "flat" | "natural" | "sharp" | "dblsharp" | "dblflat" | "quarterflat" | "quartersharp";
 type ChordPlacement = "above" | "below" | "left" | "right" | "default";
 type StemDirection = "up" | "down" | "auto" | "none";
-type AbcType = "bar_thin" | "bar_thin_thick" | "bar_thin_thin" | "bar_thick_thin" | "bar_right_repeat" | "bar_left_repeat" | "bar_double_repeat";
+type AbcType = "bar_thin" | "bar_thin_thick" | "bar_thin_thin" | "bar_thick_thin" | "bar_right_repeat" | "bar_left_repeat" | "bar_dbl_repeat";
 type AbcElementType = "note" | "bar";
 type Clef = "treble" | "tenor" | "bass" | "alto" | "treble+8" | "tenor+8" | "bass+8" | "alto+8" | "treble-8" | "tenor-8" | "bass-8" | "alto-8" | "none" | "perc";
 type NoteHeadType = "normal" | "harmonic" | "rhythm" | "x" | "triangle";
@@ -44,6 +44,7 @@ interface VoiceItemBar {
     type: AbcType;
     startChar: number;
     endChar: number;
+    startEnding?: string;
 }
 interface NoteProperties {
     duration: number;
@@ -51,6 +52,8 @@ interface NoteProperties {
     lyric?: AbcLyric[];
     chord?: AbcChord[];
     rest?: AbcRest;
+    startBeam?: boolean;
+    endBeam?: boolean;
 }
 interface VoiceItemNote extends NoteProperties {
     el_type: "note";
@@ -220,18 +223,52 @@ declare class AbcSong {
     clef: AbcClef;
     keySignature: KeySignature;
 }
-interface NoteGroupInterface {
+type NoteGroupInterface = {
     notes: string;
     lyrics: string;
-}
+};
 
-declare const parse: (abc: string) => AbcSong | undefined;
+/**
+ * Generates an AbcSong object from an ABC notation string.
+ * This function does some extra processing to handle slurs and lyrics properly.
+ * If you do not want this, use `convertStringToAbcTune` directly.
+ *
+ * @param abc
+ */
+declare const parse: (abc: string) => AbcSong;
+/**
+ * Get an info/header field from an ABC notation string.
+ * @param abc
+ * @param field
+ * @param _default
+ */
 declare const getField: (abc: string, field: string, _default?: string) => (string | undefined);
+/**
+ * Extract info/header fields from an ABC notation string into an AbcSong object and return the remaining melody string.
+ * @param abc
+ * @param song
+ */
 declare const extractInfoFields: (abc: string, song: AbcSong) => string;
-declare const extractNotesAndLyrics: (abc: string) => NoteGroupInterface;
-declare const addInfoFieldsToMelody: (song: AbcSong, abc: string) => string;
+/**
+ * Extract notes and lyrics from an ABC notation string as a single line for each.
+ * Note that you must first remove info/header fields before using this function.
+ * @param abc
+ */
+declare const squashNotesAndLyrics: (abc: string) => NoteGroupInterface;
+/**
+ * Converts and validates an ABC notation string into a TuneObject.
+ * @param abc
+ */
 declare const convertStringToAbcTune: (abc: string) => TuneObject;
-declare const combineMelodyAndLyrics: (melody: string, lyrics: string) => string;
+/**
+ * Combine multi line lyrics line with a multi line melody into a single ABC notation string.
+ * @param melody
+ * @param lyrics
+ * @param options
+ */
+declare const combineMelodyAndLyrics: (melody: string, lyrics: string, options?: {
+    trimLines?: boolean;
+}) => string;
 
 type Verse = {
     uuid: string;
@@ -247,10 +284,31 @@ type AbcMelody = {
 };
 
 declare const getForVerse: (melody: AbcMelody, verse: Verse) => AbcSubMelody | undefined;
-declare const generateAbcForVerse: (verse: Verse, activeMelody?: AbcMelody) => string;
+/**
+ * Combine an ABC melody with the lyrics of a verse into a single ABC notation string.
+ *
+ * @param verse
+ * @param activeMelody - The active melody to use. The method returns an empty string if this is undefined.
+ * @param options { trimLines?: boolean } - Whether to trim `y` spacers from start/end of lines.
+ */
+declare const generateAbcForVerse: (verse: Verse, activeMelody?: AbcMelody, options?: {
+    trimLines?: boolean;
+}) => string;
 
 declare class ValidationError extends Error {
 }
 declare function validate(result: boolean, message?: string): void;
 
-export { type AbcChord, type AbcClef, type AbcElementType, type AbcLine, type AbcLyric, type AbcMelody, type AbcPitch, type AbcPitchStartSlur, type AbcRest, AbcSong, type AbcStaff, type AbcSubMelody, type AbcType, type Accidental, type AccidentalName, type AudioTrack, type AudioTrackNote, type AudioTrackProgram, type AudioTrackText, type AudioTracks, type BracePosition, type ChordPlacement, type ChordType, type Clef, type KeyAccidentalName, type KeyRoot, type KeySignature, type MetaText, type Mode, type NoteGroupInterface, type NoteHeadType, type NoteLetter, type NoteProperties, type StemDirection, type TuneObject, ValidationError, type Verse, type VoiceItem, type VoiceItemBar, type VoiceItemClef, type VoiceItemGap, type VoiceItemKey, type VoiceItemNote, type VoiceItemStem, addInfoFieldsToMelody, combineMelodyAndLyrics, convertStringToAbcTune, extractInfoFields, extractNotesAndLyrics, generateAbcForVerse, getField, getForVerse, parse, validate };
+/**
+ * Converts an AbcSong object's info fields to ABC notation and merges them with the given melody string.
+ * @param song
+ * @param abc
+ */
+declare const addInfoFieldsToMelody: (song: AbcSong, abc: string) => string;
+/**
+ * Convert an AbcSong object to an ABC notation string.
+ * @param song
+ */
+declare const stringify: (song: AbcSong) => string;
+
+export { type AbcChord, type AbcClef, type AbcElementType, type AbcLine, type AbcLyric, type AbcMelody, type AbcPitch, type AbcPitchStartSlur, type AbcRest, AbcSong, type AbcStaff, type AbcSubMelody, type AbcType, type Accidental, type AccidentalName, type AudioTrack, type AudioTrackNote, type AudioTrackProgram, type AudioTrackText, type AudioTracks, type BracePosition, type ChordPlacement, type ChordType, type Clef, type KeyAccidentalName, type KeyRoot, type KeySignature, type MetaText, type Mode, type NoteGroupInterface, type NoteHeadType, type NoteLetter, type NoteProperties, type StemDirection, type TuneObject, ValidationError, type Verse, type VoiceItem, type VoiceItemBar, type VoiceItemClef, type VoiceItemGap, type VoiceItemKey, type VoiceItemNote, type VoiceItemStem, addInfoFieldsToMelody, combineMelodyAndLyrics, convertStringToAbcTune, extractInfoFields, generateAbcForVerse, getField, getForVerse, parse, squashNotesAndLyrics, stringify, validate };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { SynthOptions } from 'abcjs';
 type AccidentalName = "flat" | "natural" | "sharp" | "dblsharp" | "dblflat" | "quarterflat" | "quartersharp";
 type ChordPlacement = "above" | "below" | "left" | "right" | "default";
 type StemDirection = "up" | "down" | "auto" | "none";
-type AbcType = "bar_thin" | "bar_thin_thick" | "bar_thin_thin" | "bar_thick_thin" | "bar_right_repeat" | "bar_left_repeat" | "bar_double_repeat";
+type AbcType = "bar_thin" | "bar_thin_thick" | "bar_thin_thin" | "bar_thick_thin" | "bar_right_repeat" | "bar_left_repeat" | "bar_dbl_repeat";
 type AbcElementType = "note" | "bar";
 type Clef = "treble" | "tenor" | "bass" | "alto" | "treble+8" | "tenor+8" | "bass+8" | "alto+8" | "treble-8" | "tenor-8" | "bass-8" | "alto-8" | "none" | "perc";
 type NoteHeadType = "normal" | "harmonic" | "rhythm" | "x" | "triangle";
@@ -44,6 +44,7 @@ interface VoiceItemBar {
     type: AbcType;
     startChar: number;
     endChar: number;
+    startEnding?: string;
 }
 interface NoteProperties {
     duration: number;
@@ -51,6 +52,8 @@ interface NoteProperties {
     lyric?: AbcLyric[];
     chord?: AbcChord[];
     rest?: AbcRest;
+    startBeam?: boolean;
+    endBeam?: boolean;
 }
 interface VoiceItemNote extends NoteProperties {
     el_type: "note";
@@ -220,18 +223,52 @@ declare class AbcSong {
     clef: AbcClef;
     keySignature: KeySignature;
 }
-interface NoteGroupInterface {
+type NoteGroupInterface = {
     notes: string;
     lyrics: string;
-}
+};
 
-declare const parse: (abc: string) => AbcSong | undefined;
+/**
+ * Generates an AbcSong object from an ABC notation string.
+ * This function does some extra processing to handle slurs and lyrics properly.
+ * If you do not want this, use `convertStringToAbcTune` directly.
+ *
+ * @param abc
+ */
+declare const parse: (abc: string) => AbcSong;
+/**
+ * Get an info/header field from an ABC notation string.
+ * @param abc
+ * @param field
+ * @param _default
+ */
 declare const getField: (abc: string, field: string, _default?: string) => (string | undefined);
+/**
+ * Extract info/header fields from an ABC notation string into an AbcSong object and return the remaining melody string.
+ * @param abc
+ * @param song
+ */
 declare const extractInfoFields: (abc: string, song: AbcSong) => string;
-declare const extractNotesAndLyrics: (abc: string) => NoteGroupInterface;
-declare const addInfoFieldsToMelody: (song: AbcSong, abc: string) => string;
+/**
+ * Extract notes and lyrics from an ABC notation string as a single line for each.
+ * Note that you must first remove info/header fields before using this function.
+ * @param abc
+ */
+declare const squashNotesAndLyrics: (abc: string) => NoteGroupInterface;
+/**
+ * Converts and validates an ABC notation string into a TuneObject.
+ * @param abc
+ */
 declare const convertStringToAbcTune: (abc: string) => TuneObject;
-declare const combineMelodyAndLyrics: (melody: string, lyrics: string) => string;
+/**
+ * Combine multi line lyrics line with a multi line melody into a single ABC notation string.
+ * @param melody
+ * @param lyrics
+ * @param options
+ */
+declare const combineMelodyAndLyrics: (melody: string, lyrics: string, options?: {
+    trimLines?: boolean;
+}) => string;
 
 type Verse = {
     uuid: string;
@@ -247,10 +284,31 @@ type AbcMelody = {
 };
 
 declare const getForVerse: (melody: AbcMelody, verse: Verse) => AbcSubMelody | undefined;
-declare const generateAbcForVerse: (verse: Verse, activeMelody?: AbcMelody) => string;
+/**
+ * Combine an ABC melody with the lyrics of a verse into a single ABC notation string.
+ *
+ * @param verse
+ * @param activeMelody - The active melody to use. The method returns an empty string if this is undefined.
+ * @param options { trimLines?: boolean } - Whether to trim `y` spacers from start/end of lines.
+ */
+declare const generateAbcForVerse: (verse: Verse, activeMelody?: AbcMelody, options?: {
+    trimLines?: boolean;
+}) => string;
 
 declare class ValidationError extends Error {
 }
 declare function validate(result: boolean, message?: string): void;
 
-export { type AbcChord, type AbcClef, type AbcElementType, type AbcLine, type AbcLyric, type AbcMelody, type AbcPitch, type AbcPitchStartSlur, type AbcRest, AbcSong, type AbcStaff, type AbcSubMelody, type AbcType, type Accidental, type AccidentalName, type AudioTrack, type AudioTrackNote, type AudioTrackProgram, type AudioTrackText, type AudioTracks, type BracePosition, type ChordPlacement, type ChordType, type Clef, type KeyAccidentalName, type KeyRoot, type KeySignature, type MetaText, type Mode, type NoteGroupInterface, type NoteHeadType, type NoteLetter, type NoteProperties, type StemDirection, type TuneObject, ValidationError, type Verse, type VoiceItem, type VoiceItemBar, type VoiceItemClef, type VoiceItemGap, type VoiceItemKey, type VoiceItemNote, type VoiceItemStem, addInfoFieldsToMelody, combineMelodyAndLyrics, convertStringToAbcTune, extractInfoFields, extractNotesAndLyrics, generateAbcForVerse, getField, getForVerse, parse, validate };
+/**
+ * Converts an AbcSong object's info fields to ABC notation and merges them with the given melody string.
+ * @param song
+ * @param abc
+ */
+declare const addInfoFieldsToMelody: (song: AbcSong, abc: string) => string;
+/**
+ * Convert an AbcSong object to an ABC notation string.
+ * @param song
+ */
+declare const stringify: (song: AbcSong) => string;
+
+export { type AbcChord, type AbcClef, type AbcElementType, type AbcLine, type AbcLyric, type AbcMelody, type AbcPitch, type AbcPitchStartSlur, type AbcRest, AbcSong, type AbcStaff, type AbcSubMelody, type AbcType, type Accidental, type AccidentalName, type AudioTrack, type AudioTrackNote, type AudioTrackProgram, type AudioTrackText, type AudioTracks, type BracePosition, type ChordPlacement, type ChordType, type Clef, type KeyAccidentalName, type KeyRoot, type KeySignature, type MetaText, type Mode, type NoteGroupInterface, type NoteHeadType, type NoteLetter, type NoteProperties, type StemDirection, type TuneObject, ValidationError, type Verse, type VoiceItem, type VoiceItemBar, type VoiceItemClef, type VoiceItemGap, type VoiceItemKey, type VoiceItemNote, type VoiceItemStem, addInfoFieldsToMelody, combineMelodyAndLyrics, convertStringToAbcTune, extractInfoFields, generateAbcForVerse, getField, getForVerse, parse, squashNotesAndLyrics, stringify, validate };