@magmacrunch/adenosine-audio 0.2.2 → 0.2.3

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.
Files changed (3) hide show
  1. package/API.md +172 -0
  2. package/README.md +4 -0
  3. package/package.json +14 -2
package/API.md ADDED
@@ -0,0 +1,172 @@
1
+ # API Reference — adenosine-audio
2
+
3
+ Web Audio API engine for game music and sound effects.
4
+
5
+ ## Table of Contents
6
+
7
+ - [init](#init) — Initialize audio system
8
+ - [Music](#music) — Background music controls
9
+ - [SFX](#sfx) — Sound effect controls
10
+ - [Lifecycle](#lifecycle) — Visibility and cleanup
11
+ - [Types](#types)
12
+
13
+ ---
14
+
15
+ ## init
16
+
17
+ ### `init(manifest)`
18
+
19
+ Initialize the audio system with a manifest describing music and sound effects.
20
+
21
+ | Param | Type | Description |
22
+ |-------|------|-------------|
23
+ | `manifest` | `AudioManifest` | Audio configuration |
24
+
25
+ ```js
26
+ AdAudio.init({
27
+ music: { url: 'audio/music.ogg', volume: 0.7, fadeIn: 2.0 },
28
+ sfx: {
29
+ move: { url: 'audio/sfx/move.ogg', volume: 0.8 },
30
+ crash: { url: 'audio/sfx/crash.ogg', volume: 1.0, pool: 4 },
31
+ spawn: { url: 'audio/sfx/spawn.ogg' },
32
+ },
33
+ autoVisibility: true,
34
+ });
35
+ ```
36
+
37
+ ---
38
+
39
+ ## Music
40
+
41
+ ### `playMusic(fadeIn?)`
42
+
43
+ Start background music with a fade-in.
44
+
45
+ | Param | Type | Default | Description |
46
+ |-------|------|---------|-------------|
47
+ | `fadeIn` | `number` | `2.0` (from manifest) | Fade-in duration in seconds |
48
+
49
+ ### `pauseMusic()`
50
+
51
+ Pause the currently playing music.
52
+
53
+ ### `stopMusic()`
54
+
55
+ Stop the currently playing music.
56
+
57
+ ### `setMusicVolume(vol)`
58
+
59
+ Set the music volume (0.0 to 1.0).
60
+
61
+ ### `setMusicMuted(muted)`
62
+
63
+ Mute or unmute music.
64
+
65
+ ### `isMusicMuted()`
66
+
67
+ Returns `boolean` — whether music is currently muted.
68
+
69
+ ### `isMusicPlaying()`
70
+
71
+ Returns `boolean` — whether music is currently playing.
72
+
73
+ ### `toggleMusicMute()`
74
+
75
+ Toggle music mute state. Returns the new mute state (`boolean`).
76
+
77
+ ### `loadMusic(url, config?)`
78
+
79
+ Load a music track without playing it.
80
+
81
+ | Param | Type | Description |
82
+ |-------|------|-------------|
83
+ | `url` | `string` | URL of the audio file |
84
+ | `config` | `{ volume?: number; fadeIn?: number }` | Optional configuration |
85
+
86
+ ---
87
+
88
+ ## SFX
89
+
90
+ ### `playSfx(name)`
91
+
92
+ Play a named sound effect.
93
+
94
+ | Param | Type | Description |
95
+ |-------|------|-------------|
96
+ | `name` | `string` | Name defined in the manifest's `sfx` map |
97
+
98
+ ### `setSfxVolume(vol)`
99
+
100
+ Set the SFX volume (0.0 to 1.0).
101
+
102
+ ### `setSfxGlobalVolume(vol)`
103
+
104
+ Set the global SFX volume multiplier (0.0 to 1.0).
105
+
106
+ ### `setSfxMuted(muted)`
107
+
108
+ Mute or unmute all sound effects.
109
+
110
+ ### `isSfxMuted()`
111
+
112
+ Returns `boolean` — whether SFX is currently muted.
113
+
114
+ ### `toggleSfxMute()`
115
+
116
+ Toggle SFX mute state. Returns the new mute state (`boolean`).
117
+
118
+ ### `loadSfx(name, url, config?)`
119
+
120
+ Load a sound effect without playing it.
121
+
122
+ | Param | Type | Description |
123
+ |-------|------|-------------|
124
+ | `name` | `string` | Identifier for the sound |
125
+ | `url` | `string` | URL of the audio file |
126
+ | `config` | `{ volume?: number; pool?: number }` | Optional config. `pool` sets how many concurrent instances. |
127
+
128
+ ---
129
+
130
+ ## Lifecycle
131
+
132
+ ### `handleVisibility(enabled?)`
133
+
134
+ Pause/resume audio when the browser tab becomes hidden. Called automatically by `init()` unless `autoVisibility: false`.
135
+
136
+ ### `destroy()`
137
+
138
+ Clean up all audio resources (AudioContext, event listeners, pooled nodes). Call when the game unmounts.
139
+
140
+ ---
141
+
142
+ ## Types
143
+
144
+ ### `AudioManifest`
145
+
146
+ ```ts
147
+ interface AudioManifest {
148
+ music?: MusicConfig;
149
+ sfx?: Record<string, SfxConfig>;
150
+ autoVisibility?: boolean; // default: true
151
+ }
152
+ ```
153
+
154
+ ### `MusicConfig`
155
+
156
+ ```ts
157
+ interface MusicConfig {
158
+ url: string;
159
+ volume?: number; // 0.0–1.0, default 1.0
160
+ fadeIn?: number; // seconds, default 2.0
161
+ }
162
+ ```
163
+
164
+ ### `SfxConfig`
165
+
166
+ ```ts
167
+ interface SfxConfig {
168
+ url: string;
169
+ volume?: number; // 0.0–1.0, default 1.0
170
+ pool?: number; // max concurrent instances, default 3
171
+ }
172
+ ```
package/README.md CHANGED
@@ -40,6 +40,10 @@ itself off.
40
40
 
41
41
  The IIFE build is `dist/index.global.js` and exposes `window.AdAudio`.
42
42
 
43
+ ## Full API
44
+
45
+ [`API.md`](API.md) documents every export, with parameters and return shapes.
46
+
43
47
  ## License
44
48
 
45
49
  [Apache-2.0](LICENSE) — Copyright 2026 Magma Crunch Media.
package/package.json CHANGED
@@ -1,9 +1,20 @@
1
1
  {
2
2
  "name": "@magmacrunch/adenosine-audio",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "type": "module",
5
5
  "description": "Web Audio API engine for game music and sound effects",
6
6
  "license": "Apache-2.0",
7
+ "keywords": [
8
+ "web-audio",
9
+ "game-audio",
10
+ "music",
11
+ "sound-effects",
12
+ "sfx",
13
+ "game-engine"
14
+ ],
15
+ "engines": {
16
+ "node": ">=20"
17
+ },
7
18
  "repository": {
8
19
  "type": "git",
9
20
  "url": "https://github.com/magmacrunchmedia/adenosine",
@@ -21,7 +32,8 @@
21
32
  },
22
33
  "files": [
23
34
  "dist",
24
- "NOTICE"
35
+ "NOTICE",
36
+ "API.md"
25
37
  ],
26
38
  "publishConfig": {
27
39
  "access": "public"