Référence API

Chaque export public de Lulalib, groupé par catégorie : signature et rôle. Pour les explications, la syntaxe détaillée et des exemples commentés, voir la Documentation.

Sucres syntaxiques

Le point d'entrée le plus courant : construire une track mélodique ou percussive, méthode après méthode.

`bass(instrument: string): MelodicBuilder`

Piste mélodique. Alias sémantique strictement identique à lead et inst.

`lead(instrument: string): MelodicBuilder`

Piste mélodique. Alias sémantique strictement identique à bass et inst.

`inst(instrument: string): MelodicBuilder`

Piste mélodique. Alias sémantique strictement identique à bass et lead.

`drums(instrument: string): DrumsBuilder`

Piste de percussion : une part par méthode appelée.

`type MelodicBuilder`

Retourné par bass/lead/inst. Chaque méthode retourne un nouveau builder (immuable).

`.notes(pitches: string): MelodicBuilder`	le pool de hauteurs, en mini-notation de mélodie
`.rhythm(pattern: string): MelodicBuilder`	la grille de déclenchement, en mini-notation de rythme
`.step(value: string): MelodicBuilder`	durée d'un pas (défaut "1/4")
`.octave(n: number): MelodicBuilder`	octave de base pour les degrés (défaut 4)
`.build(ctx?: BuildContext): Track`	résout et retourne la Track ; appelé automatiquement par section/song
`.length: Fraction`	longueur du pattern résultant, en beats

`type DrumsBuilder`

Retourné par drums. Chaque méthode retourne un nouveau builder (immuable).

`.kick(rhythm: string): DrumsBuilder`	raccourci pour la part "kick"
`.snare(rhythm: string): DrumsBuilder`	raccourci pour la part "snare"
`.hihat(rhythm: string): DrumsBuilder`	raccourci pour la part "hihat"
`.part(name: string, rhythm: string): DrumsBuilder`	une part au nom libre
`.step(value: string): DrumsBuilder`	durée d'un pas, partagée par toutes les parts (défaut "1/4")
`.build(ctx?: BuildContext): Track`	résout et retourne la Track
`.length: Fraction`	longueur du pattern résultant, en beats

Composition

Assembler des tracks en sections, des sections en song, et exporter.

`section(tracks: Buildable[], name?: string): Section`

Empile des tracks : elles jouent simultanément. La longueur de la section est celle de sa track la plus longue.

`song(meta: { bpm: number; key?: string; timeSignature?: [number, number] }): Song`

Porte le tempo et la clé d'un arrangement. Seul bpm est obligatoire.

`track(instrument: string, spec: { notes?: string; rhythm?: string; step?: Fraction; part?: string }): Track`

API bas niveau derrière les sucres syntaxiques. Exige notes ou rhythm dans spec ; lève une erreur sinon.

`at(offset: Fraction, item: Buildable): Buildable`

Décale un élément dans le temps d'un offset donné, sans passer par le rythme.

`type Section`

{ name?: string; tracks: Buildable[]; length: Fraction; repeat(n): Section[]; with(extra): Section }

`type Song`

{ bpm; key?; timeSignature?; arrangement: Section[]; arrange(sections): Song; export(): Score }

`type Track`

{ instrument: string; pattern: Pattern<EventValue> }

`type Buildable`

Track | { length: Fraction; build(ctx?: BuildContext): Track } — ce qu'accepte section().

`type BuildContext`

{ key?: Key; baseOctave?: number } — propagé automatiquement par song.export().

Pattern (bas niveau)

Le modèle sous-jacent à toute la lib : un Pattern décrit une durée et une fonction de requête sur des fenêtres de temps. Utile pour construire ses propres abstractions au-dessus du cœur.

`type Pattern<T>`

{ length: Fraction; query(span: TimeSpan): Event<T>[] } — query ne renvoie que les events dont start est dans [span.begin, span.end).

`type Event<T>`

{ start: Fraction; dur: Fraction; value: T }

`pure<T>(value: T, dur: Fraction = frac(1)): Pattern<T>`

Un pattern à un seul event, de durée dur, démarrant à 0.

`silence<T>(length: Fraction): Pattern<T>`

Un pattern vide, de la longueur donnée. Ne produit aucun event.

`stack<T>(...patterns: Pattern<T>[]): Pattern<T>`

Fusionne des patterns qui démarrent au même instant. Longueur = celle du plus long. Events triés par start croissant.

`cat<T>(...patterns: Pattern<T>[]): Pattern<T>`

Met des patterns bout à bout, chacun décalé de la longueur cumulée des précédents. Events triés par start croissant.

`fast<T>(factor: number | Fraction, p: Pattern<T>): Pattern<T>`

Compresse un pattern dans le temps d'un facteur donné (factor > 0).

`slow<T>(factor: number | Fraction, p: Pattern<T>): Pattern<T>`

Étire un pattern dans le temps d'un facteur donné. Équivalent à fast(1/factor, p).

event(start, dur, value) · endOf(e) · shiftEvent(e, delta) · scaleEvent(e, factor)

Constructeur et utilitaires immuables sur un Event : endOf retourne start+dur, shiftEvent décale start, scaleEvent multiplie start et dur.

Export

Transformer un arrangement résolu en Score, puis le Score en JSON ou en fichier MIDI.

`toScore(tracks: Track | Track[], meta: ScoreMeta): Score`

Usage bas niveau : construit un Score directement à partir de tracks, sans passer par song.

`toJSON(score: Score, opts?: { pretty?: boolean }): string`

Sérialise le Score. pretty: true indente sur 2 espaces.

`toMIDI(score: Score, opts?: { ppq?: number }): Uint8Array`

Fichier MIDI standard (format 0, une piste). ppq fixe la résolution temporelle (défaut 480).

`type Score`

{ version; bpm; key?; timeSignature?; duration: string; instruments: Record<string, { parts?: string[] }>; events: ScoreEvent[] }

`type ScoreEvent`

{ start: string; dur: string; instrument: string; part?: string; note?: string; velocity?: number }

`type ScoreMeta`

{ bpm: number; key?: string; timeSignature?: [number, number] }

`type EventValue`

{ instrument: string; note?: string; part?: string; velocity?: number } — la valeur portée par un Event<EventValue> avant export.

type Exporter<Out> = (score: Score) => Out

Signature commune à toJSON et toMIDI, pour qui veut écrire son propre exporteur.

Théorie musicale

Résolution des notes, des degrés et des gammes. Seuls les modes majeur et mineur sont supportés.

`parseKey(entry: string): Key`

Parse une clé comme "C", "C#", "Am" ou "C#m". Le mode est déterminé par le "m" final.

`degreeToNote(key: Key, degree: number, octave: number, alteration = 0): string`

Résout un degré (1-7) en note absolue dans une clé et une octave données. alteration : -1 (bémol), 0, ou 1 (dièse).

`scaleNotes(key: Key, octave = 4): string[]`

Les 7 notes de la gamme d'une clé, dans l'octave donnée.

type Key = { root: string; mode: "major" | "minor" }

Retourné par parseKey, consommé par degreeToNote et scaleNotes.

noteToSemitones(note) · semitonesToNote(semitones) · transpose(note, semitones)

Conversions entre note absolue ("C4") et numéro MIDI de demi-ton. transpose combine les deux pour décaler une note.

Temps et fractions

Toute durée dans Lulalib est une fraction exacte, jamais un flottant. L'unité est le beat (une noire).

`type Fraction = { num: number; den: number }`

Toujours réduite au plus simple par les opérations qui la produisent.

`frac(num: number, den: number = 1): Fraction`

Construit une fraction réduite. num et den doivent être des entiers, sinon lève une erreur.

`parseFraction(value: string): Fraction`

Parse une chaîne "3/2" en Fraction. Le format attendu par .step().

add(a, b) · sub(a, b) · mul(a, b) · div(a, b)

Les quatre opérations, toutes (a: Fraction, b: Fraction) => Fraction, toujours réduites.

compare(a, b) · equals(a, b) · lt · lte · gt · gte · min(a, b) · max(a, b) · isZero(f)

compare retourne -1/0/1. Les autres sont des raccourcis booléens ou sélecteurs bâtis dessus.

toNumber(f) · toFraction(value)

toNumber calcule num/den (flottant, pour l'affichage final uniquement). toFraction accepte un number ou une Fraction et retourne toujours une Fraction.

TimeSpan

Une fenêtre de temps [begin, end), utilisée par Pattern.query pour délimiter une requête.

`type TimeSpan = { begin: Fraction; end: Fraction }`

begin doit toujours être ≤ end, sinon span() lève une erreur.

span(begin, end) · duration(s) · contains(s, t) · intersect(a, b) · shift(s, delta)

span construit un TimeSpan validé. contains teste si un instant t est dans [begin, end). intersect retourne null si les fenêtres ne se chevauchent pas.

Mini-notation

Les parseurs derrière .notes() et .rhythm(), accessibles directement pour un usage avancé.

`parseRhythm(src: string): RhythmAst`

Parse une chaîne de mini-notation de rythme en arbre syntaxique.

`parseMelody(src: string): MelodyAst`

Parse une chaîne de mini-notation de mélodie en arbre syntaxique.

`class ParseError extends Error`

{ message; position: number; notation: "rhythm" | "melody" } — levée par parseRhythm/parseMelody sur une syntaxe invalide.

RhythmAst · RhythmNode · MelodyAst · MelodyNode

Les types de l'arbre syntaxique retourné par les parseurs : trigger, hold, rest, group (rythme) ; note, chord, group (mélodie).