@jjlmoya/utils-games-development 1.50.0 → 1.52.0

package/src/tool/audioLoopPointFinder/logic.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import {
+  samplesToSeconds,
+  secondsToSamples,
+  formatTime,
+  validateLoopPoints,
+  findNearestZeroCrossing,
+  createWavWithLoopMetadata,
+  parseAudioLoopMetadata,
+  parseCommentKV,
+} from './logic';
+
+describe('audioLoopPointFinder logic', () => {
+  it('converts samples to seconds and seconds to samples', () => {
+    expect(samplesToSeconds(44100, 44100)).toBe(1);
+    expect(samplesToSeconds(22050, 44100)).toBe(0.5);
+    expect(samplesToSeconds(100, 0)).toBe(0);
+
+    expect(secondsToSamples(1, 44100)).toBe(44100);
+    expect(secondsToSamples(0.5, 44100)).toBe(22050);
+    expect(secondsToSamples(1, 0)).toBe(0);
+  });
+
+  it('formats time accurately', () => {
+    expect(formatTime(0)).toBe('00:00.000');
+    expect(formatTime(65.432)).toBe('01:05.432');
+    expect(formatTime(-5)).toBe('00:00.000');
+  });
+
+  it('validates loop points correctly', () => {
+    expect(validateLoopPoints(-10, 1000, 5000).isValid).toBe(false);
+    expect(validateLoopPoints(1000, 6000, 5000).isValid).toBe(false);
+    expect(validateLoopPoints(2000, 1000, 5000).isValid).toBe(false);
+    expect(validateLoopPoints(1000, 1050, 5000).isValid).toBe(false);
+    expect(validateLoopPoints(1000, 4000, 5000).isValid).toBe(true);
+  });
+
+  it('finds nearest zero crossing in waveform data', () => {
+    const data = new Float32Array([-0.5, -0.2, 0.1, 0.4, 0.2, -0.1, -0.3]);
+    const zeroCrossing = findNearestZeroCrossing(data, 1, 3);
+    expect(zeroCrossing).toBe(2);
+  });
+
+  it('generates valid WAV file buffer', () => {
+    const mockChannel = new Float32Array([0, 0.5, -0.5, 0]);
+    const mockAudioBuffer = {
+      numberOfChannels: 1,
+      sampleRate: 44100,
+      length: 4,
+      duration: 4 / 44100,
+      getChannelData: () => mockChannel,
+    } as unknown as AudioBuffer;
+
+    const wavBuffer = createWavWithLoopMetadata(mockAudioBuffer, 1, 3);
+    expect(wavBuffer).toBeInstanceOf(Uint8Array);
+    expect(wavBuffer.length).toBeGreaterThan(44);
+
+    const riffHeader = String.fromCharCode(wavBuffer[0] ?? 0, wavBuffer[1] ?? 0, wavBuffer[2] ?? 0, wavBuffer[3] ?? 0);
+    expect(riffHeader).toBe('RIFF');
+  });
+
+  it('parses audio loop metadata from WAV and comment KVs', () => {
+    const res: { loopStart?: number; loopEnd?: number } = {};
+    parseCommentKV('LOOPSTART=1200', res);
+    parseCommentKV('LOOPEND=4800', res);
+    expect(res.loopStart).toBe(1200);
+    expect(res.loopEnd).toBe(4800);
+
+    const emptyMeta = parseAudioLoopMetadata(new Uint8Array([0, 1, 2, 3]));
+    expect(emptyMeta.loopStart).toBeUndefined();
+  });
+});

package/src/tool/audioLoopPointFinder/logic.ts

@@ -0,0 +1,214 @@
+export interface AudioMetadata {
+  duration: number;
+  sampleRate: number;
+  numberOfChannels: number;
+  length: number;
+}
+
+export interface LoopPoints {
+  startSample: number;
+  endSample: number;
+}
+
+export interface LoopValidationResult {
+  isValid: boolean;
+  error?: string;
+}
+
+export interface SmplChunkConfig {
+  buffer: Uint8Array;
+  view: DataView;
+  sampleRate: number;
+  loopStart: number;
+  loopEnd: number;
+  offset: number;
+}
+
+export interface WavHeaderConfig {
+  buffer: Uint8Array;
+  view: DataView;
+  sampleRate: number;
+  numChannels: number;
+  totalFileSize: number;
+  blockAlign: number;
+}
+
+export {
+  parseWavLoopTags,
+  parseCommentKV,
+  parseOggVorbisComments,
+  parseAudioLoopMetadata,
+} from './metadata-parser';
+export type { ParsedLoopMetadata } from './metadata-parser';
+
+export function samplesToSeconds(samples: number, sampleRate: number): number {
+  if (sampleRate <= 0) return 0;
+  return samples / sampleRate;
+}
+
+export function secondsToSamples(seconds: number, sampleRate: number): number {
+  if (sampleRate <= 0) return 0;
+  return Math.round(seconds * sampleRate);
+}
+
+export function formatTime(seconds: number): string {
+  if (isNaN(seconds) || seconds < 0) return '00:00.000';
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  const ms = Math.floor((seconds - Math.floor(seconds)) * 1000);
+  const pad = (n: number, z = 2) => String(n).padStart(z, '0');
+  return `${pad(mins)}:${pad(secs)}.${pad(ms, 3)}`;
+}
+
+export function validateLoopPoints(startSample: number, endSample: number, totalSamples: number): LoopValidationResult {
+  if (startSample < 0) return { isValid: false, error: 'Start sample cannot be negative' };
+  if (endSample > totalSamples) return { isValid: false, error: 'End sample exceeds total audio length' };
+  if (startSample >= endSample) return { isValid: false, error: 'Start sample must be before end sample' };
+  if (endSample - startSample < 100) return { isValid: false, error: 'Loop duration is too short' };
+  return { isValid: true };
+}
+
+export function isZeroCrossingPoint(v1: number, v2: number): boolean {
+  return (v1 <= 0 && v2 >= 0) || (v1 >= 0 && v2 <= 0);
+}
+
+export function checkZeroCrossingCandidate(
+  data: Float32Array,
+  idx: number,
+  clamped: number,
+  best: { sample: number; dist: number }
+): void {
+  const val = data[idx] ?? 0;
+  const nextVal = data[idx + 1] ?? 0;
+  if (isZeroCrossingPoint(val, nextVal)) {
+    const zeroPoint = Math.abs(val) < Math.abs(nextVal) ? idx : idx + 1;
+    const dist = Math.abs(zeroPoint - clamped);
+    if (dist < best.dist) {
+      best.dist = dist;
+      best.sample = zeroPoint;
+    }
+  }
+}
+
+export function findNearestZeroCrossing(
+  channelData: Float32Array,
+  targetSample: number,
+  searchRadius: number = 500
+): number {
+  if (!channelData || channelData.length === 0) return 0;
+  const clamped = Math.max(0, Math.min(channelData.length - 1, targetSample));
+  const minIdx = Math.max(0, clamped - searchRadius);
+  const maxIdx = Math.min(channelData.length - 2, clamped + searchRadius);
+
+  const best = { sample: clamped, dist: Infinity };
+  for (let i = minIdx; i <= maxIdx; i++) {
+    checkZeroCrossingCandidate(channelData, i, clamped, best);
+  }
+
+  return best.sample;
+}
+
+export function encodePcmSamples(
+  view: DataView,
+  audioBuffer: AudioBuffer,
+  offset: number
+): void {
+  const numChannels = audioBuffer.numberOfChannels;
+  const numSamples = audioBuffer.length;
+  let currentOffset = offset;
+
+  const channels: Float32Array[] = [];
+  for (let c = 0; c < numChannels; c++) {
+    channels.push(audioBuffer.getChannelData(c));
+  }
+
+  for (let i = 0; i < numSamples; i++) {
+    for (let c = 0; c < numChannels; c++) {
+      const chData = channels[c];
+      const rawSample = chData ? (chData[i] ?? 0) : 0;
+      const sample = Math.max(-1, Math.min(1, rawSample));
+      const intSample = sample < 0 ? sample * 0x8000 : sample * 0x7FFF;
+      view.setInt16(currentOffset, Math.round(intSample), true);
+      currentOffset += 2;
+    }
+  }
+}
+
+export function writeSmplChunkData(cfg: SmplChunkConfig): number {
+  let offset = cfg.offset;
+  const writeStr = (s: string) => {
+    for (let i = 0; i < s.length; i++) cfg.buffer[offset++] = s.charCodeAt(i);
+  };
+  const write32 = (v: number) => {
+    cfg.view.setUint32(offset, v, true);
+    offset += 4;
+  };
+
+  writeStr('smpl');
+  write32(60);
+  write32(0);
+  write32(0);
+  write32(Math.round(1000000000 / cfg.sampleRate));
+  write32(60);
+  write32(0);
+  write32(0);
+  write32(0);
+  write32(1);
+  write32(0);
+  write32(0);
+  write32(0);
+  write32(cfg.loopStart);
+  write32(cfg.loopEnd);
+  write32(0);
+  write32(0);
+
+  return offset;
+}
+
+export function writeWavFmtHeader(cfg: WavHeaderConfig): number {
+  let offset = 0;
+  for (const c of 'RIFF') cfg.buffer[offset++] = c.charCodeAt(0);
+  cfg.view.setUint32(offset, cfg.totalFileSize - 8, true);
+  offset += 4;
+  for (const c of 'WAVEfmt ') cfg.buffer[offset++] = c.charCodeAt(0);
+  cfg.view.setUint32(offset, 16, true);
+  offset += 4;
+  cfg.view.setUint16(offset, 1, true);
+  offset += 2;
+  cfg.view.setUint16(offset, cfg.numChannels, true);
+  offset += 2;
+  cfg.view.setUint32(offset, cfg.sampleRate, true);
+  offset += 4;
+  cfg.view.setUint32(offset, cfg.sampleRate * cfg.blockAlign, true);
+  offset += 4;
+  cfg.view.setUint16(offset, cfg.blockAlign, true);
+  offset += 2;
+  cfg.view.setUint16(offset, 16, true);
+  offset += 2;
+  return offset;
+}
+
+export function createWavWithLoopMetadata(
+  audioBuffer: AudioBuffer,
+  loopStart: number,
+  loopEnd: number
+): Uint8Array {
+  const numChannels = audioBuffer.numberOfChannels;
+  const sampleRate = audioBuffer.sampleRate;
+  const blockAlign = numChannels * 2;
+  const dataSize = audioBuffer.length * blockAlign;
+  const totalFileSize = 112 + dataSize;
+
+  const buffer = new Uint8Array(totalFileSize);
+  const view = new DataView(buffer.buffer);
+
+  let offset = writeWavFmtHeader({ buffer, view, sampleRate, numChannels, totalFileSize, blockAlign });
+  offset = writeSmplChunkData({ buffer, view, sampleRate, loopStart, loopEnd, offset });
+
+  for (const char of 'data') buffer[offset++] = char.charCodeAt(0);
+  view.setUint32(offset, dataSize, true);
+  offset += 4;
+
+  encodePcmSamples(view, audioBuffer, offset);
+  return buffer;
+}

package/src/tool/audioLoopPointFinder/metadata-parser.ts

@@ -0,0 +1,94 @@
+export interface ParsedLoopMetadata {
+  loopStart?: number;
+  loopEnd?: number;
+}
+
+export function parseWavLoopTags(bytes: Uint8Array): ParsedLoopMetadata {
+  const result: ParsedLoopMetadata = {};
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const len = bytes.length - 12;
+
+  for (let i = 0; i < len; i++) {
+    const isSmpl = bytes[i] === 0x73 && bytes[i + 1] === 0x6d && bytes[i + 2] === 0x70 && bytes[i + 3] === 0x6c;
+    if (isSmpl && view.getUint32(i + 36, true) > 0 && i + 56 <= bytes.length) {
+      result.loopStart = view.getUint32(i + 44, true);
+      result.loopEnd = view.getUint32(i + 48, true);
+      break;
+    }
+  }
+  return result;
+}
+
+export function assignLoopKey(key: string, val: number, res: ParsedLoopMetadata): void {
+  if (key === 'LOOPSTART' || key === 'LOOP_START') res.loopStart = val;
+  else if (key === 'LOOPEND' || key === 'LOOP_END') res.loopEnd = val;
+  else if ((key === 'LOOPLENGTH' || key === 'LOOP_LENGTH') && res.loopStart !== undefined) {
+    res.loopEnd = res.loopStart + val;
+  }
+}
+
+export function parseCommentKV(kv: string, res: ParsedLoopMetadata): void {
+  const parts = kv.split('=');
+  if (parts.length < 2) return;
+  const key = (parts[0] ?? '').toUpperCase().trim();
+  const val = parseInt((parts[1] ?? '').trim(), 10);
+  if (!isNaN(val)) {
+    assignLoopKey(key, val, res);
+  }
+}
+
+export function isVorbisHeaderAt(bytes: Uint8Array, idx: number): boolean {
+  return (
+    bytes[idx] === 0x03 &&
+    bytes[idx + 1] === 118 &&
+    bytes[idx + 2] === 111 &&
+    bytes[idx + 3] === 114 &&
+    bytes[idx + 4] === 98 &&
+    bytes[idx + 5] === 105 &&
+    bytes[idx + 6] === 115
+  );
+}
+
+export function findVorbisHeaderPos(bytes: Uint8Array): number {
+  const len = bytes.length - 7;
+  for (let i = 0; i < len; i++) {
+    if (isVorbisHeaderAt(bytes, i)) return i + 7;
+  }
+  return -1;
+}
+
+export function parseOggVorbisComments(bytes: Uint8Array): ParsedLoopMetadata {
+  const res: ParsedLoopMetadata = {};
+  let pos = findVorbisHeaderPos(bytes);
+  if (pos === -1 || pos + 4 > bytes.length) return res;
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  pos += 4 + view.getUint32(pos, true);
+  if (pos + 4 > bytes.length) return res;
+
+  const userCommentCount = view.getUint32(pos, true);
+  pos += 4;
+  const decoder = new TextDecoder('utf-8');
+
+  for (let c = 0; c < userCommentCount && pos + 4 <= bytes.length; c++) {
+    const commentLen = view.getUint32(pos, true);
+    pos += 4;
+    if (pos + commentLen > bytes.length) break;
+    parseCommentKV(decoder.decode(bytes.subarray(pos, pos + commentLen)), res);
+    pos += commentLen;
+  }
+
+  return res;
+}
+
+export function getFileSignature(bytes: Uint8Array): string {
+  if (bytes.length < 4) return '';
+  return String.fromCharCode(bytes[0] ?? 0, bytes[1] ?? 0, bytes[2] ?? 0, bytes[3] ?? 0);
+}
+
+export function parseAudioLoopMetadata(bytes: Uint8Array): ParsedLoopMetadata {
+  const sig = getFileSignature(bytes);
+  if (sig === 'OggS') return parseOggVorbisComments(bytes);
+  if (sig === 'RIFF') return parseWavLoopTags(bytes);
+  return {};
+}

package/src/tool/audioLoopPointFinder/seo.astro

@@ -0,0 +1,15 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { audioLoopPointFinder } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const loader = audioLoopPointFinder.i18n[locale] ?? audioLoopPointFinder.i18n.en;
+const content = loader ? await loader() : null;
+---
+
+{content && content.seo && content.seo.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/audioLoopPointFinder/ui.ts

@@ -0,0 +1,42 @@
+export interface AudioLoopPointFinderUI extends Record<string, string> {
+  title: string;
+  subtitle: string;
+  dropzoneTitle: string;
+  dropzoneSubtitle: string;
+  dropzoneButton: string;
+  audioInfoTitle: string;
+  durationLabel: string;
+  sampleRateLabel: string;
+  channelsLabel: string;
+  totalSamplesLabel: string;
+  loopControlsTitle: string;
+  loopStartLabel: string;
+  loopEndLabel: string;
+  loopDurationLabel: string;
+  zeroCrossingLabel: string;
+  snapZeroCrossingButton: string;
+  playLoopButton: string;
+  pauseLoopButton: string;
+  stopLoopButton: string;
+  exportWavButton: string;
+  sampleUnitLabel: string;
+  secondUnitLabel: string;
+  zoomLabel: string;
+  zoomInButton: string;
+  zoomOutButton: string;
+  resetZoomButton: string;
+  noFileSelected: string;
+  invalidAudioFile: string;
+  presetsTitle: string;
+  presetFullTrack: string;
+  presetIntroCut: string;
+  presetMiddleLoop: string;
+  statusLooping: string;
+  statusPaused: string;
+  statusReady: string;
+  statusLoaded: string;
+  statusDecodeError: string;
+  statusSnapped: string;
+  statusStopped: string;
+  statusExported: string;
+}

package/src/tool/audioLoopPointFinder/waveform-renderer.ts

@@ -0,0 +1,53 @@
+export interface WaveformOverlayConfig {
+  ctx: CanvasRenderingContext2D;
+  loopStartSample: number;
+  loopEndSample: number;
+  totalSamples: number;
+  width: number;
+  height: number;
+}
+
+export function renderWaveformBars(
+  ctx: CanvasRenderingContext2D,
+  audioBuffer: AudioBuffer,
+  width: number,
+  height: number
+) {
+  const channelData = audioBuffer.getChannelData(0);
+  const step = Math.ceil(channelData.length / width);
+  const amp = height / 2;
+
+  ctx.fillStyle = '#4f46e5';
+  for (let i = 0; i < width; i++) {
+    let min = 1.0;
+    let max = -1.0;
+    for (let j = 0; j < step; j++) {
+      const datum = channelData[i * step + j] ?? 0;
+      if (datum < min) min = datum;
+      if (datum > max) max = datum;
+    }
+    ctx.fillRect(i, (1 + min) * amp, 1, Math.max(1, (max - min) * amp));
+  }
+}
+
+export function renderWaveformOverlay(cfg: WaveformOverlayConfig) {
+  const startX = (cfg.loopStartSample / cfg.totalSamples) * cfg.width;
+  const endX = (cfg.loopEndSample / cfg.totalSamples) * cfg.width;
+
+  cfg.ctx.fillStyle = 'rgba(99, 102, 241, 0.2)';
+  cfg.ctx.fillRect(startX, 0, Math.max(1, endX - startX), cfg.height);
+
+  cfg.ctx.strokeStyle = '#10b981';
+  cfg.ctx.lineWidth = 2;
+  cfg.ctx.beginPath();
+  cfg.ctx.moveTo(startX, 0);
+  cfg.ctx.lineTo(startX, cfg.height);
+  cfg.ctx.stroke();
+
+  cfg.ctx.strokeStyle = '#ef4444';
+  cfg.ctx.lineWidth = 2;
+  cfg.ctx.beginPath();
+  cfg.ctx.moveTo(endX, 0);
+  cfg.ctx.lineTo(endX, cfg.height);
+  cfg.ctx.stroke();
+}

package/src/tool/saveFileEditor/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { bibliographyEntries } from './bibliography';
+---
+
+<SharedBibliography links={bibliographyEntries} />

package/src/tool/saveFileEditor/bibliography.ts

@@ -0,0 +1,12 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliographyEntries: BibliographyEntry[] = [
+  {
+    name: 'Game Save Data Architecture (Game Developer Article)',
+    url: 'https://www.gamedeveloper.com/programming/game-save-data-architecture',
+  },
+  {
+    name: 'RFC 4648 - The Base16, Base32, and Base64 Data Encodings',
+    url: 'https://datatracker.ietf.org/doc/html/rfc4648',
+  },
+];