ts-flp 1.0.4 → 1.0.6

package/README.md

@@ -160,6 +160,14 @@ interface PluginRef {
 | `getFlVersion(parsed)`               | Get the FL Studio version string                   |
 | `getPPQ(parsed)`                     | Get the PPQ (Pulses Per Quarter note)              |
 
+### Write behavior
+
+- `undefined` leaves the corresponding value unchanged.
+- `null` clears text metadata, leaves BPM unchanged, and resets time values to zero.
+- Missing metadata and timestamp events are created in the project preamble.
+- BPM values are validated against the limits supported by the detected FL Studio version.
+- Invalid dates, negative work times, and non-finite numeric values throw an error.
+
 ## Constraints and limitations
 
 ### What this library does
@@ -197,6 +205,9 @@ src/
 # Install dependencies
 pnpm install
 
+# Add at least one private .flp file directly to test_projs/
+# These fixtures are ignored by Git and are required by the integration tests.
+
 # Type checking
 pnpm run typecheck
 
@@ -215,7 +226,7 @@ pnpm run build
 
 ## License
 
-[GPL-3.0](LICENSE)
+[MIT](LICENSE)
 
 ---
 

package/dist/index.cjs

@@ -65,6 +65,9 @@ var WORD = 64;
 var DWORD = 128;
 var TEXT = 192;
 var DATA = 208;
+var FIXED_SIZE_OVERRIDES = {
+  172: 3
+};
 var NEW_TEXT_IDS = [
   TEXT + 49,
   // ArrangementID.Name
@@ -211,6 +214,7 @@ var EVENT_ID = {
   // 236
 };
 var EVENT_KIND = {
+  [172]: "unknown",
   // Project events
   [EVENT_ID.PROJECT_LOOP_ACTIVE]: "u8",
   [EVENT_ID.PROJECT_SHOW_INFO]: "u8",
@@ -319,6 +323,10 @@ function getEventKind(eventId) {
   }
 }
 function getEventFixedSize(eventId) {
+  const override = FIXED_SIZE_OVERRIDES[eventId];
+  if (override !== void 0) {
+    return override;
+  }
   if (eventId < WORD) {
     return 1;
   } else if (eventId < DWORD) {
@@ -609,8 +617,8 @@ function parseFlp(buffer) {
     throw new Error(`Invalid header size: expected ${FLP_HEADER_SIZE}, got ${headerSize}`);
   }
   const format = reader.readI16LE();
-  const channelCount = reader.readU16LE();
-  const ppq = reader.readU16LE();
+  reader.readU16LE();
+  reader.readU16LE();
   if (format < -1 || format > 80) {
     throw new Error(`Invalid file format: ${format}`);
   }
@@ -630,7 +638,6 @@ function parseFlp(buffer) {
   const events = [];
   let flVersion = "0.0.0";
   let useUnicode = false;
-  let detectedVersion = false;
   const eventsStart = reader.tell();
   const eventsEnd = eventsStart + eventsSize;
   while (reader.tell() < eventsEnd) {
@@ -638,14 +645,9 @@ function parseFlp(buffer) {
     const eventId = reader.readU8();
     let payloadSize;
     let headerSize2;
-    if (eventId < WORD) {
-      payloadSize = 1;
-      headerSize2 = 1;
-    } else if (eventId < DWORD) {
-      payloadSize = 2;
-      headerSize2 = 1;
-    } else if (eventId < TEXT) {
-      payloadSize = 4;
+    const fixedSize = getEventFixedSize(eventId);
+    if (fixedSize >= 0) {
+      payloadSize = fixedSize;
       headerSize2 = 1;
     } else {
       const sizeStart = reader.tell();
@@ -662,16 +664,14 @@ function parseFlp(buffer) {
       payload: Buffer.from(payload)
     };
     events.push(event);
-    if (eventId === EVENT_ID.PROJECT_FL_VERSION && !detectedVersion) {
+    if (eventId === EVENT_ID.PROJECT_FL_VERSION && flVersion === "0.0.0") {
       const candidate = payload.toString("ascii").replace(/\0/g, "").trim();
-      const isSemverLike = /^\d+(\.\d+)+$/.test(candidate);
-      if (isSemverLike) {
+      if (/^\d+(\.\d+)+$/.test(candidate)) {
         flVersion = candidate;
         const parts = flVersion.split(".").map((p) => parseInt(p, 10));
         const major = parts[0] ?? 0;
         const minor = parts[1] ?? 0;
         useUnicode = parts.length >= 2 && (major > 11 || major === 11 && minor >= 5);
-        detectedVersion = true;
       }
     }
   }
@@ -738,7 +738,7 @@ function createEvent(id, payload) {
 function patchEvents(parsed, patcher) {
   const patchedEvents = parsed.events.map((event, index) => {
     const patched = patcher(event, index);
-    if (patched.payload !== event.payload && patched.id >= TEXT) {
+    if (patched.payload !== event.payload && event.header.length > 1) {
       const headerWriter = new BinaryWriter();
       headerWriter.writeU8(patched.id);
       headerWriter.writeVarInt(patched.payload.length);
@@ -831,62 +831,166 @@ function createNumberPayload(value, kind) {
 }
 
 // src/api/ProjectApi.ts
+var PROJECT_EVENT_ORDER = [
+  EVENT_ID.PROJECT_TEMPO,
+  EVENT_ID.PROJECT_TITLE,
+  EVENT_ID.PROJECT_GENRE,
+  EVENT_ID.PROJECT_ARTISTS,
+  EVENT_ID.PROJECT_COMMENTS,
+  EVENT_ID.PROJECT_TIMESTAMP
+];
+function insertProjectEvent(parsed, event) {
+  const orderIndex = PROJECT_EVENT_ORDER.indexOf(event.id);
+  let insertionIndex = -1;
+  if (orderIndex >= 0) {
+    const laterIds = new Set(PROJECT_EVENT_ORDER.slice(orderIndex + 1));
+    insertionIndex = parsed.events.findIndex((candidate) => laterIds.has(candidate.id));
+    if (insertionIndex < 0) {
+      const previousIds = new Set(PROJECT_EVENT_ORDER.slice(0, orderIndex + 1));
+      for (let index = parsed.events.length - 1; index >= 0; index--) {
+        if (previousIds.has(parsed.events[index].id)) {
+          insertionIndex = index + 1;
+          break;
+        }
+      }
+    }
+  }
+  if (insertionIndex < 0) {
+    insertionIndex = parsed.events.findIndex((candidate) => candidate.id === EVENT_ID.CHANNEL_NEW);
+  }
+  if (insertionIndex < 0) {
+    const versionIndex = parsed.events.findIndex(
+      (candidate) => candidate.id === EVENT_ID.PROJECT_FL_VERSION
+    );
+    insertionIndex = versionIndex >= 0 ? versionIndex + 1 : parsed.events.length;
+  }
+  const events = [...parsed.events];
+  events.splice(insertionIndex, 0, event);
+  return { ...parsed, events };
+}
+function replaceEventPayload(parsed, target, payload) {
+  return patchEvents(parsed, (event) => event === target ? { ...event, payload } : event);
+}
+function readBpm(parsed) {
+  const tempoEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TEMPO);
+  if (tempoEvent) {
+    return getEventNumber(tempoEvent) / 1e3;
+  }
+  const coarseEvent = findFirstEvent(parsed, EVENT_ID.PROJECT__TEMPO_COARSE);
+  if (coarseEvent) {
+    let bpm = coarseEvent.payload.readUInt16LE(0);
+    const fineEvent = findFirstEvent(parsed, EVENT_ID.PROJECT__TEMPO_FINE);
+    if (fineEvent) {
+      bpm += fineEvent.payload.readUInt16LE(0) / 1e3;
+    }
+    return bpm;
+  }
+  return null;
+}
 function readProjectMeta(parsed) {
   const titleEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TITLE);
   const commentsEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_COMMENTS);
   const artistsEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_ARTISTS);
   const genreEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_GENRE);
-  const tempoEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TEMPO);
   return {
     name: titleEvent ? getEventString(titleEvent, parsed.useUnicode) : null,
     description: commentsEvent ? getEventString(commentsEvent, parsed.useUnicode) : null,
     artist: artistsEvent ? getEventString(artistsEvent, parsed.useUnicode) : null,
     genre: genreEvent ? getEventString(genreEvent, parsed.useUnicode) : null,
-    bpm: tempoEvent ? getEventNumber(tempoEvent) / 1e3 : null
+    bpm: readBpm(parsed)
   };
 }
+function compareVersion(version, expected) {
+  const actual = version.split(".").map((part) => Number.parseInt(part, 10));
+  const length = Math.max(actual.length, expected.length);
+  for (let index = 0; index < length; index++) {
+    const difference = (actual[index] ?? 0) - (expected[index] ?? 0);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return 0;
+}
+function validateBpm(parsed, bpm) {
+  if (!Number.isFinite(bpm)) {
+    throw new RangeError("BPM must be a finite number");
+  }
+  const legacyHighTempo = compareVersion(parsed.flVersion, [1, 4, 2]) >= 0 && compareVersion(parsed.flVersion, [11]) < 0;
+  const maximum = legacyHighTempo ? 999 : 522;
+  if (bpm < 10 || bpm > maximum) {
+    throw new RangeError(`BPM must be between 10 and ${maximum} for FL Studio ${parsed.flVersion}`);
+  }
+  if (parsed.flVersion !== "0.0.0" && compareVersion(parsed.flVersion, [3, 4]) < 0 && !Number.isInteger(bpm)) {
+    throw new TypeError(`FL Studio ${parsed.flVersion} does not support decimal BPM values`);
+  }
+}
+function writeTextProjectEvent(parsed, eventId, value) {
+  if (value === void 0) return parsed;
+  const payload = createTextPayload(value ?? "", parsed.useUnicode);
+  const existing = findFirstEvent(parsed, eventId);
+  return existing ? replaceEventPayload(parsed, existing, payload) : insertProjectEvent(parsed, createEvent(eventId, payload));
+}
+function writeProjectBpm(parsed, bpm) {
+  if (bpm === void 0 || bpm === null) return parsed;
+  validateBpm(parsed, bpm);
+  const scaledBpm = Math.round(bpm * 1e3);
+  const coarseBpm = Math.floor(scaledBpm / 1e3);
+  const fineBpm = scaledBpm % 1e3;
+  const modernEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TEMPO);
+  const coarseEvent = findFirstEvent(parsed, EVENT_ID.PROJECT__TEMPO_COARSE);
+  const fineEvent = findFirstEvent(parsed, EVENT_ID.PROJECT__TEMPO_FINE);
+  let result = parsed;
+  if (modernEvent) {
+    result = replaceEventPayload(result, modernEvent, createNumberPayload(scaledBpm, "u32"));
+  }
+  if (coarseEvent) {
+    result = replaceEventPayload(result, coarseEvent, createNumberPayload(coarseBpm, "u16"));
+  }
+  if (fineEvent) {
+    result = replaceEventPayload(result, fineEvent, createNumberPayload(fineBpm, "u16"));
+  }
+  if (!modernEvent && !coarseEvent && !fineEvent) {
+    result = insertProjectEvent(
+      result,
+      createEvent(EVENT_ID.PROJECT_TEMPO, createNumberPayload(scaledBpm, "u32"))
+    );
+  } else if (!modernEvent && coarseEvent && !fineEvent && fineBpm > 0) {
+    const updatedCoarse = findFirstEvent(result, EVENT_ID.PROJECT__TEMPO_COARSE);
+    const index = result.events.indexOf(updatedCoarse) + 1;
+    const events = [...result.events];
+    events.splice(
+      index,
+      0,
+      createEvent(EVENT_ID.PROJECT__TEMPO_FINE, createNumberPayload(fineBpm, "u16"))
+    );
+    result = { ...result, events };
+  } else if (!modernEvent && !coarseEvent && fineEvent) {
+    const updatedFine = findFirstEvent(result, EVENT_ID.PROJECT__TEMPO_FINE);
+    const index = result.events.indexOf(updatedFine);
+    const events = [...result.events];
+    events.splice(
+      index,
+      0,
+      createEvent(EVENT_ID.PROJECT__TEMPO_COARSE, createNumberPayload(coarseBpm, "u16"))
+    );
+    result = { ...result, events };
+  }
+  return result;
+}
 function writeProjectMeta(parsed, meta) {
-  return patchEvents(parsed, (event) => {
-    if (meta.name !== void 0 && event.id === EVENT_ID.PROJECT_TITLE) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.name ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.description !== void 0 && event.id === EVENT_ID.PROJECT_COMMENTS) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.description ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.artist !== void 0 && event.id === EVENT_ID.PROJECT_ARTISTS) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.artist ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.genre !== void 0 && event.id === EVENT_ID.PROJECT_GENRE) {
-      return {
-        ...event,
-        payload: createTextPayload(meta.genre ?? "", parsed.useUnicode)
-      };
-    }
-    if (meta.bpm && Math.abs(meta.bpm) > 0 && event.id === EVENT_ID.PROJECT_TEMPO) {
-      return {
-        ...event,
-        payload: createNumberPayload(Math.round(Math.abs(meta.bpm) * 1e3), "u32")
-      };
-    }
-    return event;
-  });
+  let result = parsed;
+  result = writeProjectBpm(result, meta.bpm);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_TITLE, meta.name);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_GENRE, meta.genre);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_ARTISTS, meta.artist);
+  result = writeTextProjectEvent(result, EVENT_ID.PROJECT_COMMENTS, meta.description);
+  return result;
 }
-var DELPHI_EPOCH = new Date(1899, 11, 30);
+var DELPHI_EPOCH_MS = Date.UTC(1899, 11, 30);
 function delphiToDate(days) {
   const ms = days * 24 * 60 * 60 * 1e3;
-  return new Date(DELPHI_EPOCH.getTime() + ms);
+  return new Date(DELPHI_EPOCH_MS + ms);
 }
 function dateToDelphiDays(date) {
-  const ms = date.getTime() - DELPHI_EPOCH.getTime();
+  const ms = date.getTime() - DELPHI_EPOCH_MS;
   return ms / (24 * 60 * 60 * 1e3);
 }
 function readProjectTimeInfo(parsed) {
@@ -907,31 +1011,23 @@ function readProjectTimeInfo(parsed) {
   };
 }
 function writeProjectTimeInfo(parsed, info) {
+  if (info.creationDate === void 0 && info.workTimeSeconds === void 0) {
+    return parsed;
+  }
   const current = readProjectTimeInfo(parsed);
-  return patchEvents(parsed, (event) => {
-    if (event.id !== EVENT_ID.PROJECT_TIMESTAMP) {
-      return event;
-    }
-    const writer = new BinaryWriter();
-    if (info.creationDate !== void 0 && info.creationDate !== null) {
-      writer.writeF64LE(dateToDelphiDays(info.creationDate));
-    } else if (current.creationDate !== null) {
-      writer.writeF64LE(dateToDelphiDays(current.creationDate));
-    } else {
-      writer.writeF64LE(0);
-    }
-    if (info.workTimeSeconds !== void 0 && info.workTimeSeconds !== null) {
-      writer.writeF64LE(info.workTimeSeconds / (24 * 60 * 60));
-    } else if (current.workTimeSeconds !== null) {
-      writer.writeF64LE(current.workTimeSeconds / (24 * 60 * 60));
-    } else {
-      writer.writeF64LE(0);
-    }
-    return {
-      ...event,
-      payload: writer.toBuffer()
-    };
-  });
+  if (info.creationDate !== void 0 && info.creationDate !== null && Number.isNaN(info.creationDate.getTime())) {
+    throw new RangeError("creationDate must be a valid Date");
+  }
+  if (info.workTimeSeconds !== void 0 && info.workTimeSeconds !== null && (!Number.isFinite(info.workTimeSeconds) || info.workTimeSeconds < 0)) {
+    throw new RangeError("workTimeSeconds must be a finite, non-negative number");
+  }
+  const creationDateDays = info.creationDate === null ? 0 : info.creationDate !== void 0 ? dateToDelphiDays(info.creationDate) : current.creationDate !== null ? dateToDelphiDays(current.creationDate) : 0;
+  const workTimeDays = info.workTimeSeconds === null ? 0 : info.workTimeSeconds !== void 0 ? info.workTimeSeconds / (24 * 60 * 60) : current.workTimeSeconds !== null ? current.workTimeSeconds / (24 * 60 * 60) : 0;
+  const writer = new BinaryWriter();
+  writer.writeF64LE(creationDateDays);
+  writer.writeF64LE(workTimeDays);
+  const timestampEvent = findFirstEvent(parsed, EVENT_ID.PROJECT_TIMESTAMP);
+  return timestampEvent ? replaceEventPayload(parsed, timestampEvent, writer.toBuffer()) : insertProjectEvent(parsed, createEvent(EVENT_ID.PROJECT_TIMESTAMP, writer.toBuffer()));
 }
 function listSamples(parsed) {
   const samples = [];