@goldenratio/wolf 0.0.2

package/LICENSE

@@ -0,0 +1,18 @@
+zlib License
+
+Copyright (c) 2025 Karthik Jayakumar (@goldenratio)
+
+This software is provided "as-is", without any express or implied warranty. In no event
+will the authors be held liable for any damages arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose, including commercial
+applications, and to alter it and redistribute it freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not claim that you
+  wrote the original software. If you use this software in a product, an acknowledgment
+  in the product documentation would be appreciated but is not required.
+
+  2. Altered source versions must be plainly marked as such, and must not be misrepresented
+  as being the original software.
+
+  3. This notice may not be removed or altered from any source distribution.

package/README.md

@@ -0,0 +1,33 @@
+# wolf
+> Javascript audio library for the modern web. Port of howler.js in TypeScript (ESM)
+
+### What is different from original [Howler.js](https://github.com/goldfire/howler.js)
+
+- Written in TypeScript (better type safety)
+- Compatible with [Google Closure Compiler](https://github.com/google/closure-compiler)
+- ESM only
+
+## Install
+
+### NPM
+
+```console
+npm install --save @goldenratio/wolf
+```
+
+https://www.npmjs.com/package/@goldenratio/wolf
+
+## Release
+
+### NPM
+```console
+npm version {major | minor | patch}
+npm publish
+
+# If you have ignore-scripts enabled
+npm version {major | minor | patch}
+npm run version
+npm run postversion
+npm publish
+
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@goldenratio/wolf",
+  "version": "0.0.2",
+  "description": "Port of howler.js in TypeScript (ESM)",
+  "type": "module",
+  "module": "./target/wolf.js",
+  "types": "./target/types/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./target/types/main.d.ts",
+      "import": "./target/wolf.js"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf target js",
+    "build": "npm run clean && tsc && node ./build.ts",
+    "test": "node --import tsx --test ./tests/*.test.ts",
+    "generate-docs": "rm -rf ./docs && typedoc --theme default --excludePrivate --excludeProtected",
+    "version": "npm run build",
+    "postversion": "git push && git push --tags"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/goldenratio/wolf.git"
+  },
+  "author": "Karthik Jayakumar",
+  "license": "Zlib",
+  "bugs": {
+    "url": "https://codeberg.org/goldenratio/wolf"
+  },
+  "files": [
+    "target/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://codeberg.org/goldenratio/wolf",
+  "devDependencies": {
+    "@types/node": "25.0.10",
+    "esbuild": "0.27.2",
+    "typedoc": "0.28.16",
+    "typescript": "5.9.3"
+  }
+}

package/target/types/howl.d.ts

@@ -0,0 +1,132 @@
+import type { HowlEventHandler, HowlEventName, HowlListener, HowlOptions, HowlState, HowlXHR, HowlSpriteMap, WebAudioNodeWithSource } from "./types.js";
+import { Sound } from "./sound.js";
+export declare class Howl {
+    private readonly howler;
+    _autoplay: boolean;
+    _format: readonly string[] | undefined;
+    _html5: boolean;
+    _muted: boolean;
+    _loop: boolean;
+    _pool: number;
+    _preload: boolean | "metadata" | "none";
+    _rate: number;
+    _sprite: HowlSpriteMap;
+    _src: readonly string[];
+    _volume: number;
+    _xhr: HowlXHR;
+    _duration: number;
+    _state: HowlState;
+    _sounds: Sound[];
+    _endTimers: Record<number, ReturnType<typeof setTimeout> | (() => void)>;
+    _queue: Array<{
+        event: string;
+        action: () => void;
+    }>;
+    _playLock: boolean;
+    _webAudio: boolean;
+    _onend: HowlListener[];
+    _onfade: HowlListener[];
+    _onload: HowlListener[];
+    _onloaderror: HowlListener[];
+    _onplayerror: HowlListener[];
+    _onpause: HowlListener[];
+    _onplay: HowlListener[];
+    _onstop: HowlListener[];
+    _onmute: HowlListener[];
+    _onvolume: HowlListener[];
+    _onrate: HowlListener[];
+    _onseek: HowlListener[];
+    _onunlock: HowlListener[];
+    _onresume: HowlListener[];
+    constructor(options: HowlOptions);
+    load(): void;
+    play(spriteOrId?: string | number, internal?: boolean): number | undefined;
+    state(): HowlState;
+    /**
+     * Check if a sound (or any sound) is playing.
+     */
+    playing(id?: number): boolean;
+    /**
+     * Duration of group, or sprite duration if sound id passed.
+     */
+    duration(id?: number): number;
+    /**
+     * Pause playback and save current position.
+     */
+    pause(id?: number, internal?: boolean): this;
+    /**
+     * Get/set playback rate.
+     *  rate() -> first sound rate (or group rate fallback)
+     *  rate(id) -> sound rate
+     *  rate(rate) -> set group rate
+     *  rate(rate, id) -> set sound rate
+     */
+    rate(): number;
+    rate(id: number): number;
+    rate(rate: number): this;
+    rate(rate: number, id: number): this;
+    /**
+       * Get/set seek position.
+       *  seek() -> first sound seek
+       *  seek(id) -> sound seek
+       *  seek(seek) -> set first sound seek
+       *  seek(seek, id) -> set sound seek
+       */
+    seek(): number;
+    seek(id: number): number;
+    seek(seek: number): this;
+    seek(seek: number, id: number): this;
+    stop(id?: number, internal?: boolean): this;
+    /**
+     * Mute/unmute a single sound or all sounds in this Howl group.
+     * @param muted Set to true to mute and false to unmute.
+     * @param id The sound ID to update (omit to mute/unmute all).
+     */
+    mute(muted?: boolean, id?: number): this | boolean;
+    /**
+     * Get/set the volume of this sound or of the Howl group.
+     *  volume() -> group volume
+     *  volume(id) -> sound volume
+     *  volume(vol) -> set group volume
+     *  volume(vol, id) -> set sound volume
+     */
+    volume(): number;
+    volume(id: number): number;
+    volume(vol: number): this;
+    volume(vol: number, id: number): this;
+    volume(vol: number, id: number, internal?: boolean): this;
+    /**
+     * Fade a currently playing sound between two volumes (if no id is passed, all sounds will fade).
+     */
+    fade(from: number, to: number, len: number, id?: number): this;
+    /**
+     * loop() from your snippet.
+     */
+    loop(): boolean;
+    loop(id: number): boolean;
+    loop(loop: boolean): this;
+    loop(loop: boolean, id: number): this;
+    unload(): void;
+    on(event: HowlEventName, fn: HowlEventHandler, id?: number, once?: boolean): this;
+    off(event?: HowlEventName, fn?: HowlEventHandler | number, id?: number): this;
+    once(event: HowlEventName, fn: HowlEventHandler, id?: number): this;
+    /**
+     * Starts the internal interval to fade a sound.
+     */
+    private _startFadeInterval;
+    /**
+     * Stop an active fade.
+     */
+    private _stopFade;
+    _emit(event: HowlEventName, id?: number, errorMsg?: string): this;
+    _loadQueue(event?: string): this;
+    _ended(sound: Sound): this;
+    _clearTimer(id: number): this;
+    _soundById(id: number): Sound | undefined;
+    _inactiveSound(): Sound;
+    _drain(): void;
+    _getSoundIds(id?: number): number[];
+    _refreshBuffer(sound: Sound): void;
+    _cleanBuffer(node: WebAudioNodeWithSource): void;
+    _clearSound(node: HTMLAudioElement): void;
+}

package/target/types/howler.d.ts

@@ -0,0 +1,42 @@
+import type { Howl } from "./howl.js";
+import type { HowlerState, Html5AudioUnlocked } from "./types.js";
+declare class HowlerGlobal {
+    _counter: number;
+    _html5AudioPool: Html5AudioUnlocked[];
+    html5PoolSize: number;
+    _codecs: Record<string, boolean>;
+    _howls: Howl[];
+    _muted: boolean;
+    _volume: number;
+    _canPlayEvent: "canplaythrough" | "canplay";
+    readonly _navigator?: Navigator;
+    _audioUnlocked?: boolean;
+    _mobileUnloaded?: boolean;
+    _scratchBuffer?: AudioBuffer;
+    _suspendTimer?: ReturnType<typeof setTimeout>;
+    _resumeAfterSuspend?: boolean;
+    cache: Record<string, AudioBuffer>;
+    masterGain?: GainNode;
+    noAudio: boolean;
+    usingWebAudio: boolean;
+    autoSuspend: boolean;
+    ctx?: AudioContext;
+    autoUnlock: boolean;
+    state: HowlerState;
+    constructor();
+    volume(): number;
+    volume(volume: number): this;
+    mute(muted: boolean): this;
+    stop(): this;
+    unload(): this;
+    codecs(ext: string): boolean;
+    _setup(): void;
+    _setupCodecs(): void;
+    _unlockAudio(): void;
+    _obtainHtml5Audio(): Html5AudioUnlocked;
+    _releaseHtml5Audio(audio: Html5AudioUnlocked): this;
+    _autoSuspend(): void;
+    _autoResume(): void;
+}
+export declare const Howler: HowlerGlobal;
+export {};

package/target/types/main.d.ts

@@ -0,0 +1,3 @@
+export { Howler } from "./howler.js";
+export { Howl } from "./howl.js";
+export * from "./types.js";

package/target/types/sound.d.ts

@@ -0,0 +1,32 @@
+import type { Howl } from "./howl.js";
+import type { SoundNode } from "./types.js";
+import type { Howler } from "./howler.js";
+export declare class Sound {
+    private readonly howler;
+    private readonly parent;
+    _muted: boolean;
+    _loop: boolean;
+    _volume: number;
+    _rate: number;
+    _seek: number;
+    _rateSeek: number;
+    _paused: boolean;
+    _ended: boolean;
+    _sprite: string;
+    _id: number;
+    _node?: SoundNode;
+    _panner?: AudioNode;
+    _start: number;
+    _stop: number;
+    _playStart: number;
+    _interval?: ReturnType<typeof setTimeout>;
+    _fadeTo?: number;
+    _errorFn?: (ev: Event) => void;
+    _loadFn?: (ev: Event) => void;
+    _endFn?: (ev: Event) => void;
+    constructor(parent: Howl, howler: typeof Howler);
+    reset(): this;
+    private errorListener;
+    private loadListener;
+    private endListener;
+}

package/target/types/types.d.ts

@@ -0,0 +1,52 @@
+export type HowlState = "unloaded" | "loading" | "loaded";
+export type HowlerState = "suspended" | "suspending" | "running";
+export type HowlEventName = "end" | "fade" | "load" | "loaderror" | "playerror" | "pause" | "play" | "stop" | "mute" | "volume" | "rate" | "seek" | "unlock" | "resume";
+export type HowlEventHandler = (soundId?: number, errorMsg?: string) => void;
+export interface HowlListener {
+    readonly id?: number;
+    readonly fn: HowlEventHandler;
+    readonly once?: boolean;
+}
+export interface HowlXHR {
+    readonly method: string;
+    readonly withCredentials: boolean;
+    readonly headers?: Record<string, string>;
+}
+export type HowlSpriteDef = [startMs: number, durationMs: number, loop?: boolean];
+export type HowlSpriteMap = Record<string, HowlSpriteDef>;
+export interface HowlOptions {
+    readonly src: string | readonly string[];
+    readonly autoplay?: boolean;
+    readonly format?: string | readonly string[];
+    readonly html5?: boolean;
+    readonly mute?: boolean;
+    readonly loop?: boolean;
+    readonly pool?: number;
+    readonly preload?: boolean | "metadata" | "none";
+    readonly rate?: number;
+    readonly sprite?: HowlSpriteMap;
+    readonly volume?: number;
+    readonly xhr?: Partial<HowlXHR>;
+    readonly onend?: HowlEventHandler;
+    readonly onfade?: HowlEventHandler;
+    readonly onload?: HowlEventHandler;
+    readonly onloaderror?: HowlEventHandler;
+    readonly onplayerror?: HowlEventHandler;
+    readonly onpause?: HowlEventHandler;
+    readonly onplay?: HowlEventHandler;
+    readonly onstop?: HowlEventHandler;
+    readonly onmute?: HowlEventHandler;
+    readonly onvolume?: HowlEventHandler;
+    readonly onrate?: HowlEventHandler;
+    readonly onseek?: HowlEventHandler;
+    readonly onunlock?: HowlEventHandler;
+    readonly onresume?: HowlEventHandler;
+}
+export interface WebAudioNodeWithSource extends GainNode {
+    bufferSource?: AudioBufferSourceNode;
+    paused?: boolean;
+}
+export interface Html5AudioUnlocked extends HTMLAudioElement {
+    _unlocked?: boolean;
+}
+export type SoundNode = WebAudioNodeWithSource | Html5AudioUnlocked;

package/target/types/utils.d.ts

@@ -0,0 +1,8 @@
+import type { Howl } from "./howl.js";
+import type { Html5AudioUnlocked, SoundNode } from "./types.js";
+import type { Howler } from "./howler.js";
+export declare function isHtml5Audio(node: SoundNode): node is Html5AudioUnlocked;
+export declare function loadBuffer(howl: Howl, howler: typeof Howler): void;
+export declare function safeXhrSend(xhr: XMLHttpRequest): void;
+export declare function loadSound(self: Howl, buffer?: AudioBuffer): void;
+export declare function setupAudioContext(howler: typeof Howler): void;