winamp-eqf 0.0.0-next-c2c0675

package/README.md

@@ -0,0 +1,90 @@
+# Winamp Equalizer Preset Parser
+
+Winamp allows you to save your equalizer settings to `.eqf` file. This package allows you to parse these files.
+
+## Installation
+
+```bash
+npm install --save winamp-eqf
+```
+
+## Usage
+
+```typescript
+import { parser, creator, EqfData, CreateEqfData } from 'winamp-eqf';
+
+// ... Get your .eqf or .q1 file as an ArrayBuffer
+const eqf: EqfData = parser(eqfArrayBuffer);
+
+const eqfArrayBuffer: ArrayBuffer = creator(eqf);
+```
+
+This package is an ES module and requires Node.js 14+ or a modern bundler that supports ES modules.
+
+## API
+
+This package is written in TypeScript and provides full type definitions.
+
+### `parser(ArrayBuffer): EqfData`
+
+#### Return value
+
+```JavaScript
+{
+  "presets": [
+    {
+      "name": "Entry1",
+      "preamp": 33, // 1-64
+      "hz60": 64,   // 1-64
+      "hz170": 64,  // ...
+      "hz310": 64,
+      "hz600": 64,
+      "hz1000": 64,
+      "hz3000": 64,
+      "hz6000": 64,
+      "hz12000": 64,
+      "hz14000": 64,
+      "hz16000": 64,
+    },
+    // Some files, such as winamp.q1, may contain multiple preset objects.
+  ],
+  "type": "Winamp EQ library file v1.1",
+}
+```
+
+### `creator(eqfObject: CreateEqfData): ArrayBuffer`
+
+#### Return Value: `ArrayBuffer`
+
+`eqfObject` is an object with the same shape as that returned by `parser()`.
+
+
+
+## Source Material
+
+Starting with this spec found here: <http://www.perlmonks.org/bare/?node_id=584875>:
+
+> I've taken a look at some EQF files that I made for the purpose. The format is apparently very simple:
+> The file is 299 bytes long.
+>
+> It starts with a text header, which in my case, is 37 bytes long. It is, in double-quotish notation — note the control-Z character:
+>
+> Winamp EQ library file v1.1\cZ!--Entry1
+>
+> Next is a block of null bytes ("\0") up till the next, final part.
+> The real data is stored in the last 11 bytes of the file: the last byte is for the general volume, the 10 bytes before that are for each of the 10 EQ controls, in ascending order: the first of these 10 for the deepest bass, the last one (right in front of the volume byte) is for the highest treble.
+> The values are 0x20 in neutral position, and are reversed in value: 0x00 is maximum, 0x3F is minimum. So there are 31 positions below, and 31 32 levels above neutral.
+
+Additionally, I got some info from [Darren Owen](https://twitter.com/The_DoctorO) via Twitter:
+
+<https://twitter.com/The_DoctorO/status/856223002530373632>
+
+> Not that i'm aware off as sadly documentation of things was never great. Looking at the link vs files in a hex editor it seems mostly right.
+
+> The current 1.1 format should be fine as I don't believe the format has changed for a very long time :)
+
+And then via direct message:
+
+> Will do it here as I can type a bit more, but the only obvious thing wrong with the link is the signature assumption as it's not guaranteed to be 'entry1' As you can have multiple eq blocks in a file.
+
+> If you've looked at winamp.q1 you should see multiple presets in that file which follow one after each other so the file signature (winamp.q1 or a specific *.eqf file) is "Winamp EQ library file v1.1\x1A!--" (pulled that out from the disassembler) it's then a 257 byte buffer (256 + null character to terminate correctly) then the 10 byte block relating to the eq sliders (need to double-check the range base) followed by the 1 byte for the preamp slider then if there's more presets in the file, they follow on immediately after with the name block looking at the preamp slider, -12dB = 0x3F, 0dB = 0x1F, 12dB = 0 (so a 0-63 range) that seems to be the same for the other sliders (and matches 1:1 with the sdk details) and I think that's it :) in the winamp.q1 file, the 'default' entry is either a flat preset or what's been saved after customisation (in-case you're wanting to mirror the native behaviour via the preset -> save -> default action)

package/built/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const PRESET_VALUES: readonly ["hz60", "hz170", "hz310", "hz600", "hz1000", "hz3000", "hz6000", "hz12000", "hz14000", "hz16000", "preamp"];
+export declare const HEADER = "Winamp EQ library file v1.1";
+export type PresetValueKey = (typeof PRESET_VALUES)[number];
+//# sourceMappingURL=constants.d.ts.map

package/built/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,uHAYhB,CAAC;AAEX,eAAO,MAAM,MAAM,gCAAgC,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/built/constants.js

@@ -0,0 +1,14 @@
+export const PRESET_VALUES = [
+    "hz60",
+    "hz170",
+    "hz310",
+    "hz600",
+    "hz1000",
+    "hz3000",
+    "hz6000",
+    "hz12000",
+    "hz14000",
+    "hz16000",
+    "preamp",
+];
+export const HEADER = "Winamp EQ library file v1.1";

package/built/creator.d.ts

@@ -0,0 +1,3 @@
+import { CreateEqfData } from "./types.js";
+export declare function creator(data: CreateEqfData): ArrayBuffer;
+//# sourceMappingURL=creator.d.ts.map

package/built/creator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creator.d.ts","sourceRoot":"","sources":["../src/creator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3C,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,WAAW,CAqCxD"}

package/built/creator.js

@@ -0,0 +1,34 @@
+import { HEADER, PRESET_VALUES } from "./constants.js";
+const PRESET_LENGTH = 257;
+export function creator(data) {
+    const buffer = [];
+    // Add header
+    for (let i = 0; i < HEADER.length; i++) {
+        buffer.push(HEADER.charCodeAt(i));
+    }
+    // Add control character and ending
+    buffer.push(26); // <ctrl-z>
+    const ending = "!--";
+    for (let i = 0; i < ending.length; i++) {
+        buffer.push(ending.charCodeAt(i));
+    }
+    if (!data.presets) {
+        throw new Error("Eqf data is missing presets");
+    }
+    data.presets.forEach((preset) => {
+        // Add preset name
+        let k = 0;
+        for (; k < preset.name.length; k++) {
+            buffer.push(preset.name.charCodeAt(k));
+        }
+        // Pad name to fixed length
+        for (; k < PRESET_LENGTH; k++) {
+            buffer.push(0);
+        }
+        // Add preset values
+        PRESET_VALUES.forEach((valueName) => {
+            buffer.push(64 - preset[valueName]); // Adjust for inverse values
+        });
+    });
+    return new Uint8Array(buffer).buffer;
+}

package/built/index.d.ts

@@ -0,0 +1,5 @@
+export { parser } from "./parser.js";
+export { creator } from "./creator.js";
+export * from "./types.js";
+export * from "./constants.js";
+//# sourceMappingURL=index.d.ts.map

package/built/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/built/index.js

@@ -0,0 +1,4 @@
+export { parser } from "./parser.js";
+export { creator } from "./creator.js";
+export * from "./types.js";
+export * from "./constants.js";

package/built/parser.d.ts

@@ -0,0 +1,3 @@
+import { EqfData } from "./types.js";
+export declare function parser(arrayBuffer: ArrayBuffer): EqfData;
+//# sourceMappingURL=parser.d.ts.map

package/built/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAa,MAAM,YAAY,CAAC;AAEhD,wBAAgB,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CA+CxD"}

package/built/parser.js

@@ -0,0 +1,36 @@
+import { HEADER, PRESET_VALUES } from "./constants.js";
+export function parser(arrayBuffer) {
+    const data = {
+        type: "",
+        presets: [],
+    };
+    let i = 0;
+    const arr = new Int8Array(arrayBuffer);
+    // Parse header
+    data.type = String.fromCharCode.apply(null, Array.from(arr.slice(i, HEADER.length)));
+    if (data.type !== HEADER) {
+        throw new Error("Invalid .eqf file.");
+    }
+    i += HEADER.length;
+    // Skip "<ctrl-z>!--"
+    i += 4;
+    // Get the presets
+    while (i < arr.length) {
+        const preset = {};
+        // Get the name
+        const nameStart = i;
+        const nameEnd = nameStart + 257; // Str is fixed length
+        // Str is null terminated
+        while (arr[i] !== 0 && i <= nameEnd) {
+            i++;
+        }
+        preset.name = String.fromCharCode.apply(null, Array.from(arr.slice(nameStart, i)));
+        i = nameEnd; // Skip over any unused bytes
+        // Get the levels
+        PRESET_VALUES.forEach((valueName) => {
+            preset[valueName] = 64 - arr[i++]; // Adjust for inverse values
+        });
+        data.presets.push(preset);
+    }
+    return data;
+}

package/built/types.d.ts

@@ -0,0 +1,27 @@
+import { PresetValueKey } from "./constants.js";
+export interface EqfPreset {
+    name: string;
+    hz60: number;
+    hz170: number;
+    hz310: number;
+    hz600: number;
+    hz1000: number;
+    hz3000: number;
+    hz6000: number;
+    hz12000: number;
+    hz14000: number;
+    hz16000: number;
+    preamp: number;
+}
+export interface EqfData {
+    type: string;
+    presets: EqfPreset[];
+}
+export interface CreateEqfData {
+    presets: Array<{
+        [K in PresetValueKey]: number;
+    } & {
+        name: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/built/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CACZ;SACG,CAAC,IAAI,cAAc,GAAG,MAAM;KAC9B,GAAG;QACF,IAAI,EAAE,MAAM,CAAC;KACd,CACF,CAAC;CACH"}

package/built/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "winamp-eqf",
+  "version": "0.0.0-next-c2c0675",
+  "description": "Parse and create Winamp .EQF files which describe equalizer settings",
+  "type": "module",
+  "main": "built/index.js",
+  "types": "built/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./built/index.js",
+      "types": "./built/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/captbaritone/webamp.git",
+    "directory": "packages/winamp-eqf"
+  },
+  "bugs": {
+    "url": "https://github.com/captbaritone/webamp/issues"
+  },
+  "homepage": "https://github.com/captbaritone/webamp/tree/master/packages/winamp-eqf",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "type-check": "tsc --noEmit"
+  },
+  "files": [
+    "built/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "winamp",
+    "equalizer",
+    "parse",
+    "create"
+  ],
+  "author": "Jordan Eldredge",
+  "license": "ISC",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@swc/jest": "^0.2.24",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.10",
+    "buffer-to-arraybuffer": "0.0.4",
+    "typescript": "^5.3.3"
+  },
+  "jest": {
+    "modulePathIgnorePatterns": [
+      "built"
+    ],
+    "testEnvironment": "jsdom",
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "transform": {
+      "^.+\\.(t|j)sx?$": [
+        "@swc/jest"
+      ]
+    }
+  }
+}