@xromdev/apu 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/sweep.js ADDED
@@ -0,0 +1,79 @@
1
+ /**
2
+ * The pulse channels' sweep unit (`$4001`/`$4005`), as pure functions.
3
+ *
4
+ * The chip uses these per half-frame; `sweepTrace` runs the same unit over one
5
+ * note so a chart of an effect's pitch can show the period the chip PLAYS rather
6
+ * than the one the data holds — for a swept sound those are not the same line.
7
+ */
8
+ /** Rate the sweep unit and the length counters are clocked at — the half-frame. */
9
+ export const SWEEP_HZ = 120;
10
+ export function decodeSweep(value, pulse1) {
11
+ return {
12
+ enabled: (value & 0x80) !== 0,
13
+ dividerPeriod: (value >> 4) & 7,
14
+ negate: (value & 0x08) !== 0,
15
+ shift: value & 7,
16
+ pulse1,
17
+ };
18
+ }
19
+ /**
20
+ * The period the sweep unit would move to.
21
+ *
22
+ * Pulse 1 subtracts one MORE than pulse 2 — a hardware asymmetry, not a typo:
23
+ * pulse 1 negates with one's complement and pulse 2 with two's.
24
+ */
25
+ export function sweepTarget(period, sweep) {
26
+ const change = period >> sweep.shift;
27
+ if (!sweep.negate)
28
+ return period + change;
29
+ return period - change - (sweep.pulse1 ? 1 : 0);
30
+ }
31
+ /**
32
+ * Is the channel silenced by the sweep unit?
33
+ *
34
+ * Two conditions, and both hold **whether or not the unit is enabled**: a
35
+ * period below 8, and a target above `$7FF`. That second one surprises people —
36
+ * with `$4001` at its power-on value of 0 (shift 0, add) every period from
37
+ * `$400` up targets past `$7FF`, so a low pulse note is mute until something
38
+ * writes the register. Drivers write `$08` (negate) for exactly this reason.
39
+ */
40
+ export function sweepMutes(period, sweep) {
41
+ if (period < 8)
42
+ return true;
43
+ return sweepTarget(period, sweep) > 0x7ff;
44
+ }
45
+ /**
46
+ * The period the sweep unit holds at each half-frame of one note.
47
+ *
48
+ * `null` in the returned array is a half-frame where the unit mutes the channel.
49
+ *
50
+ * @param sweep the `$4001` byte; -1 or undefined gives a flat trace
51
+ * @param channel 0 pulse 1, 1 pulse 2; anything else has no sweep unit
52
+ */
53
+ export function sweepTrace(period, sweep, channel, halfFrames) {
54
+ const config = channel < 2 && sweep !== undefined && sweep >= 0 ? decodeSweep(sweep, channel === 0) : null;
55
+ const out = [];
56
+ if (!config || period < 1) {
57
+ for (let i = 0; i < halfFrames; i++)
58
+ out.push(period < 1 ? null : period);
59
+ return out;
60
+ }
61
+ let current = period;
62
+ let divider = config.dividerPeriod;
63
+ let reload = true;
64
+ for (let i = 0; i < halfFrames; i++) {
65
+ out.push(sweepMutes(current, config) ? null : current);
66
+ if (divider === 0 && config.enabled && config.shift > 0 && !sweepMutes(current, config)) {
67
+ current = Math.max(0, sweepTarget(current, config));
68
+ }
69
+ if (divider === 0 || reload) {
70
+ divider = config.dividerPeriod;
71
+ reload = false;
72
+ }
73
+ else {
74
+ divider -= 1;
75
+ }
76
+ }
77
+ return out;
78
+ }
79
+ //# sourceMappingURL=sweep.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sweep.js","sourceRoot":"","sources":["../src/sweep.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pulse channels' sweep unit (`$4001`/`$4005`), as pure functions.\n *\n * The chip uses these per half-frame; `sweepTrace` runs the same unit over one\n * note so a chart of an effect's pitch can show the period the chip PLAYS rather\n * than the one the data holds — for a swept sound those are not the same line.\n */\n\n/** Rate the sweep unit and the length counters are clocked at — the half-frame. */\nexport const SWEEP_HZ = 120;\n\n/**\n * `$4001` taken apart: `EPPP NSSS`.\n *\n * `pulse1` is not in the register — it is which channel it belongs to — but it\n * belongs here because the subtraction differs between the two channels by one,\n * and that one is audible as most of a semitone at short periods.\n */\nexport interface SweepConfig {\n enabled: boolean;\n /** Reload value for the divider: the unit acts every `dividerPeriod + 1` half-frames. */\n dividerPeriod: number;\n negate: boolean;\n shift: number;\n pulse1: boolean;\n}\n\nexport function decodeSweep(value: number, pulse1: boolean): SweepConfig {\n return {\n enabled: (value & 0x80) !== 0,\n dividerPeriod: (value >> 4) & 7,\n negate: (value & 0x08) !== 0,\n shift: value & 7,\n pulse1,\n };\n}\n\n/**\n * The period the sweep unit would move to.\n *\n * Pulse 1 subtracts one MORE than pulse 2 — a hardware asymmetry, not a typo:\n * pulse 1 negates with one's complement and pulse 2 with two's.\n */\nexport function sweepTarget(period: number, sweep: SweepConfig): number {\n const change = period >> sweep.shift;\n if (!sweep.negate) return period + change;\n return period - change - (sweep.pulse1 ? 1 : 0);\n}\n\n/**\n * Is the channel silenced by the sweep unit?\n *\n * Two conditions, and both hold **whether or not the unit is enabled**: a\n * period below 8, and a target above `$7FF`. That second one surprises people —\n * with `$4001` at its power-on value of 0 (shift 0, add) every period from\n * `$400` up targets past `$7FF`, so a low pulse note is mute until something\n * writes the register. Drivers write `$08` (negate) for exactly this reason.\n */\nexport function sweepMutes(period: number, sweep: SweepConfig): boolean {\n if (period < 8) return true;\n return sweepTarget(period, sweep) > 0x7ff;\n}\n\n/**\n * The period the sweep unit holds at each half-frame of one note.\n *\n * `null` in the returned array is a half-frame where the unit mutes the channel.\n *\n * @param sweep the `$4001` byte; -1 or undefined gives a flat trace\n * @param channel 0 pulse 1, 1 pulse 2; anything else has no sweep unit\n */\nexport function sweepTrace(\n period: number,\n sweep: number | undefined,\n channel: number,\n halfFrames: number\n): (number | null)[] {\n const config =\n channel < 2 && sweep !== undefined && sweep >= 0 ? decodeSweep(sweep, channel === 0) : null;\n const out: (number | null)[] = [];\n if (!config || period < 1) {\n for (let i = 0; i < halfFrames; i++) out.push(period < 1 ? null : period);\n return out;\n }\n\n let current = period;\n let divider = config.dividerPeriod;\n let reload = true;\n for (let i = 0; i < halfFrames; i++) {\n out.push(sweepMutes(current, config) ? null : current);\n if (divider === 0 && config.enabled && config.shift > 0 && !sweepMutes(current, config)) {\n current = Math.max(0, sweepTarget(current, config));\n }\n if (divider === 0 || reload) {\n divider = config.dividerPeriod;\n reload = false;\n } else {\n divider -= 1;\n }\n }\n return out;\n}\n"]}
package/package.json ADDED
@@ -0,0 +1,59 @@
1
+ {
2
+ "name": "@xromdev/apu",
3
+ "version": "0.1.0",
4
+ "description": "The NES sound chip (2A03 APU) in TypeScript: register writes in, samples out.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js"
13
+ },
14
+ "./package.json": "./package.json"
15
+ },
16
+ "files": [
17
+ "dist",
18
+ "README.md",
19
+ "LICENSE"
20
+ ],
21
+ "sideEffects": false,
22
+ "scripts": {
23
+ "build": "tsc -p tsconfig.build.json",
24
+ "test": "vitest run",
25
+ "typecheck": "tsc -p tsconfig.json --noEmit",
26
+ "prepare": "npm run build",
27
+ "prepublishOnly": "npm run typecheck && npm test"
28
+ },
29
+ "keywords": [
30
+ "nes",
31
+ "famicom",
32
+ "apu",
33
+ "2a03",
34
+ "chiptune",
35
+ "synth",
36
+ "audio",
37
+ "emulator",
38
+ "ricoh"
39
+ ],
40
+ "repository": {
41
+ "type": "git",
42
+ "url": "git+https://github.com/DeepNESReverse/xrom-apu.git"
43
+ },
44
+ "homepage": "https://github.com/DeepNESReverse/xrom-apu#readme",
45
+ "bugs": {
46
+ "url": "https://github.com/DeepNESReverse/xrom-apu/issues"
47
+ },
48
+ "engines": {
49
+ "node": ">=18"
50
+ },
51
+ "devDependencies": {
52
+ "typescript": "^5.9.3",
53
+ "vitest": "^3.2.7"
54
+ },
55
+ "author": "Oleksandr Maksymov",
56
+ "publishConfig": {
57
+ "access": "public"
58
+ }
59
+ }