ts-flp 1.0.5 → 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) {
@@ -595,62 +603,9 @@ function varIntSize(value) {
 }
 
 // src/parser/FlpParser.ts
-var KNOWN_DWORD_IDS = new Set(
-  Object.keys(EVENT_KIND).map(Number).filter((id) => id >= DWORD && id < TEXT)
-);
 var FLP_HEADER_MAGIC = "FLhd";
 var FLP_DATA_MAGIC = "FLdt";
 var FLP_HEADER_SIZE = 6;
-var LOOKAHEAD_BYTES = 200;
-var LOOKAHEAD_VARINT_MAX = 1e5;
-function readVarIntRaw(buf, off, end) {
-  let shift = 0;
-  let size = 0;
-  const start = off;
-  while (true) {
-    if (off >= end) return { size: -1, bytesRead: 0 };
-    const byte = buf[off];
-    off++;
-    size |= (byte & 127) << shift;
-    shift += 7;
-    if (!(byte & 128)) break;
-  }
-  return { size, bytesRead: off - start };
-}
-function scoreAlignment(buf, off, end, bytesToCheck) {
-  const limit = Math.min(off + bytesToCheck, end);
-  let textDataCount = 0;
-  let consecutiveSmallByte = 0;
-  let maxConsecutiveSmallByte = 0;
-  while (off < limit) {
-    const id = buf[off];
-    if (id < WORD) {
-      off += 2;
-      if (id < 32 && !KNOWN_DWORD_IDS.has(id)) {
-        consecutiveSmallByte++;
-        maxConsecutiveSmallByte = Math.max(maxConsecutiveSmallByte, consecutiveSmallByte);
-      } else {
-        consecutiveSmallByte = 0;
-      }
-    } else if (id < DWORD) {
-      off += 3;
-      consecutiveSmallByte = 0;
-    } else if (id < TEXT) {
-      off += 5;
-      consecutiveSmallByte = 0;
-    } else {
-      const vi = readVarIntRaw(buf, off + 1, end);
-      if (vi.size >= 0 && vi.size < LOOKAHEAD_VARINT_MAX && off + 1 + vi.bytesRead + vi.size <= end) {
-        textDataCount++;
-        off = off + 1 + vi.bytesRead + vi.size;
-      } else {
-        return -100;
-      }
-      consecutiveSmallByte = 0;
-    }
-  }
-  return textDataCount * 10 - maxConsecutiveSmallByte * 3;
-}
 function parseFlp(buffer) {
   const reader = new BinaryReader(buffer);
   const headerMagic = reader.readBytes(4).toString("ascii");
@@ -662,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}`);
   }
@@ -690,39 +645,10 @@ function parseFlp(buffer) {
     const eventId = reader.readU8();
     let payloadSize;
     let headerSize2;
-    if (eventId < WORD) {
-      payloadSize = 1;
+    const fixedSize = getEventFixedSize(eventId);
+    if (fixedSize >= 0) {
+      payloadSize = fixedSize;
       headerSize2 = 1;
-    } else if (eventId < DWORD) {
-      payloadSize = 2;
-      headerSize2 = 1;
-    } else if (eventId < TEXT) {
-      if (KNOWN_DWORD_IDS.has(eventId)) {
-        payloadSize = 4;
-        headerSize2 = 1;
-      } else {
-        const afterDword = eventStart + 1 + 4;
-        const vi = readVarIntRaw(buffer, eventStart + 1, eventsEnd);
-        if (vi.size < 0 || vi.size > LOOKAHEAD_VARINT_MAX || eventStart + 1 + vi.bytesRead + vi.size > eventsEnd) {
-          payloadSize = 4;
-          headerSize2 = 1;
-        } else if (vi.size === 3) {
-          payloadSize = 4;
-          headerSize2 = 1;
-        } else {
-          const afterVarInt = eventStart + 1 + vi.bytesRead + vi.size;
-          const dwordScore = scoreAlignment(buffer, afterDword, eventsEnd, LOOKAHEAD_BYTES);
-          const varIntScore = scoreAlignment(buffer, afterVarInt, eventsEnd, LOOKAHEAD_BYTES);
-          if (varIntScore > dwordScore + 2) {
-            payloadSize = vi.size;
-            reader.seek(eventStart + 1 + vi.bytesRead);
-            headerSize2 = 1 + vi.bytesRead;
-          } else {
-            payloadSize = 4;
-            headerSize2 = 1;
-          }
-        }
-      }
     } else {
       const sizeStart = reader.tell();
       payloadSize = reader.readVarInt();
@@ -905,6 +831,46 @@ 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) {
@@ -934,48 +900,97 @@ function readProjectMeta(parsed) {
     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) {
@@ -996,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 = [];