@antha/audio 0.0.1

package/dist/codecs.d.ts

@@ -0,0 +1,292 @@
+/**
+ * The codec determining code is largely copied from
+ * https://github.com/goldfire/howler.js/blob/a2a47933f1ffcee659e4939a65e075fa7f25706c/src/howler.core.js,
+ * which has the following license:
+ *
+ *     Copyright (c) 2013-2020 James Simpson and GoldFire Studios, Inc.
+ *
+ *     Permission is hereby granted, free of charge, to any person obtaining
+ *     a copy of this software and associated documentation files (the
+ *     "Software"), to deal in the Software without restriction, including
+ *     without limitation the rights to use, copy, modify, merge, publish,
+ *     distribute, sublicense, and/or sell copies of the Software, and to
+ *     permit persons to whom the Software is furnished to do so, subject to
+ *     the following conditions:
+ *
+ *     The above copyright notice and this permission notice shall be
+ *     included in all copies or substantial portions of the Software.
+ *
+ *     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ *     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ *     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ *     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ *     LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ *     OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ *     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+import { type Values } from '@augment-vir/common';
+/**
+ * An enum of audio codec names.
+ *
+ * @category Internal
+ */
+export declare const Codec: {
+    mp3: "mp3";
+    mpeg: "mp3";
+    opus: "mp3";
+    ogg: "mp3";
+    oga: "mp3";
+    wav: "mp3";
+    aac: "mp3";
+    caf: "mp3";
+    m4a: "mp3";
+    m4b: "mp3";
+    mp4: "mp3";
+    weba: "mp3";
+    webm: "mp3";
+    dolby: "mp3";
+    flac: "mp3";
+} | {
+    mp3: "mpeg";
+    mpeg: "mpeg";
+    opus: "mpeg";
+    ogg: "mpeg";
+    oga: "mpeg";
+    wav: "mpeg";
+    aac: "mpeg";
+    caf: "mpeg";
+    m4a: "mpeg";
+    m4b: "mpeg";
+    mp4: "mpeg";
+    weba: "mpeg";
+    webm: "mpeg";
+    dolby: "mpeg";
+    flac: "mpeg";
+} | {
+    mp3: "opus";
+    mpeg: "opus";
+    opus: "opus";
+    ogg: "opus";
+    oga: "opus";
+    wav: "opus";
+    aac: "opus";
+    caf: "opus";
+    m4a: "opus";
+    m4b: "opus";
+    mp4: "opus";
+    weba: "opus";
+    webm: "opus";
+    dolby: "opus";
+    flac: "opus";
+} | {
+    mp3: "ogg";
+    mpeg: "ogg";
+    opus: "ogg";
+    ogg: "ogg";
+    oga: "ogg";
+    wav: "ogg";
+    aac: "ogg";
+    caf: "ogg";
+    m4a: "ogg";
+    m4b: "ogg";
+    mp4: "ogg";
+    weba: "ogg";
+    webm: "ogg";
+    dolby: "ogg";
+    flac: "ogg";
+} | {
+    mp3: "oga";
+    mpeg: "oga";
+    opus: "oga";
+    ogg: "oga";
+    oga: "oga";
+    wav: "oga";
+    aac: "oga";
+    caf: "oga";
+    m4a: "oga";
+    m4b: "oga";
+    mp4: "oga";
+    weba: "oga";
+    webm: "oga";
+    dolby: "oga";
+    flac: "oga";
+} | {
+    mp3: "wav";
+    mpeg: "wav";
+    opus: "wav";
+    ogg: "wav";
+    oga: "wav";
+    wav: "wav";
+    aac: "wav";
+    caf: "wav";
+    m4a: "wav";
+    m4b: "wav";
+    mp4: "wav";
+    weba: "wav";
+    webm: "wav";
+    dolby: "wav";
+    flac: "wav";
+} | {
+    mp3: "aac";
+    mpeg: "aac";
+    opus: "aac";
+    ogg: "aac";
+    oga: "aac";
+    wav: "aac";
+    aac: "aac";
+    caf: "aac";
+    m4a: "aac";
+    m4b: "aac";
+    mp4: "aac";
+    weba: "aac";
+    webm: "aac";
+    dolby: "aac";
+    flac: "aac";
+} | {
+    mp3: "caf";
+    mpeg: "caf";
+    opus: "caf";
+    ogg: "caf";
+    oga: "caf";
+    wav: "caf";
+    aac: "caf";
+    caf: "caf";
+    m4a: "caf";
+    m4b: "caf";
+    mp4: "caf";
+    weba: "caf";
+    webm: "caf";
+    dolby: "caf";
+    flac: "caf";
+} | {
+    mp3: "m4a";
+    mpeg: "m4a";
+    opus: "m4a";
+    ogg: "m4a";
+    oga: "m4a";
+    wav: "m4a";
+    aac: "m4a";
+    caf: "m4a";
+    m4a: "m4a";
+    m4b: "m4a";
+    mp4: "m4a";
+    weba: "m4a";
+    webm: "m4a";
+    dolby: "m4a";
+    flac: "m4a";
+} | {
+    mp3: "m4b";
+    mpeg: "m4b";
+    opus: "m4b";
+    ogg: "m4b";
+    oga: "m4b";
+    wav: "m4b";
+    aac: "m4b";
+    caf: "m4b";
+    m4a: "m4b";
+    m4b: "m4b";
+    mp4: "m4b";
+    weba: "m4b";
+    webm: "m4b";
+    dolby: "m4b";
+    flac: "m4b";
+} | {
+    mp3: "mp4";
+    mpeg: "mp4";
+    opus: "mp4";
+    ogg: "mp4";
+    oga: "mp4";
+    wav: "mp4";
+    aac: "mp4";
+    caf: "mp4";
+    m4a: "mp4";
+    m4b: "mp4";
+    mp4: "mp4";
+    weba: "mp4";
+    webm: "mp4";
+    dolby: "mp4";
+    flac: "mp4";
+} | {
+    mp3: "weba";
+    mpeg: "weba";
+    opus: "weba";
+    ogg: "weba";
+    oga: "weba";
+    wav: "weba";
+    aac: "weba";
+    caf: "weba";
+    m4a: "weba";
+    m4b: "weba";
+    mp4: "weba";
+    weba: "weba";
+    webm: "weba";
+    dolby: "weba";
+    flac: "weba";
+} | {
+    mp3: "webm";
+    mpeg: "webm";
+    opus: "webm";
+    ogg: "webm";
+    oga: "webm";
+    wav: "webm";
+    aac: "webm";
+    caf: "webm";
+    m4a: "webm";
+    m4b: "webm";
+    mp4: "webm";
+    weba: "webm";
+    webm: "webm";
+    dolby: "webm";
+    flac: "webm";
+} | {
+    mp3: "dolby";
+    mpeg: "dolby";
+    opus: "dolby";
+    ogg: "dolby";
+    oga: "dolby";
+    wav: "dolby";
+    aac: "dolby";
+    caf: "dolby";
+    m4a: "dolby";
+    m4b: "dolby";
+    mp4: "dolby";
+    weba: "dolby";
+    webm: "dolby";
+    dolby: "dolby";
+    flac: "dolby";
+} | {
+    mp3: "flac";
+    mpeg: "flac";
+    opus: "flac";
+    ogg: "flac";
+    oga: "flac";
+    wav: "flac";
+    aac: "flac";
+    caf: "flac";
+    m4a: "flac";
+    m4b: "flac";
+    mp4: "flac";
+    weba: "flac";
+    webm: "flac";
+    dolby: "flac";
+    flac: "flac";
+};
+/**
+ * An enum of audio codec names.
+ *
+ * @category Internal
+ */
+export type Codec = Values<typeof Codec>;
+/**
+ * Check if the given audio codec/extension is supported in the current browser.
+ *
+ * @category Internal
+ */
+export declare function isCodecSupported(codec: string): boolean;
+/**
+ * Check if the given audio file is supported in the current browser by extracting its file
+ * extension.
+ *
+ * @category Internal
+ */
+export declare function isFileSupported(fileName: string): boolean;

package/dist/codecs.js

@@ -0,0 +1,101 @@
+/**
+ * The codec determining code is largely copied from
+ * https://github.com/goldfire/howler.js/blob/a2a47933f1ffcee659e4939a65e075fa7f25706c/src/howler.core.js,
+ * which has the following license:
+ *
+ *     Copyright (c) 2013-2020 James Simpson and GoldFire Studios, Inc.
+ *
+ *     Permission is hereby granted, free of charge, to any person obtaining
+ *     a copy of this software and associated documentation files (the
+ *     "Software"), to deal in the Software without restriction, including
+ *     without limitation the rights to use, copy, modify, merge, publish,
+ *     distribute, sublicense, and/or sell copies of the Software, and to
+ *     permit persons to whom the Software is furnished to do so, subject to
+ *     the following conditions:
+ *
+ *     The above copyright notice and this permission notice shall be
+ *     included in all copies or substantial portions of the Software.
+ *
+ *     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ *     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ *     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ *     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ *     LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ *     OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ *     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+import { mapObjectValues } from '@augment-vir/common';
+function readCodecs() {
+    const audioTest = new Audio();
+    /* node:coverage disable: there's no way to reasonably test all the different below possibilities. */
+    const mpegTest = !!audioTest.canPlayType('audio/mpeg;');
+    // Opera version <33 has mixed MP3 support, so we need to check for and block it.
+    const userAgent = globalThis.navigator.userAgent;
+    const operaAgent = userAgent.match(/OPR\/(\d+)/g);
+    const operaVersion = operaAgent?.[0].split('/')[1];
+    const isOldOpera = operaAgent && operaVersion ? parseInt(operaVersion) < 33 : false;
+    const checkSafari = userAgent.includes('Safari') && !userAgent.includes('Chrome');
+    const safariVersion = userAgent.match(/Version\/(.*?) /)?.[1];
+    const isOldSafari = checkSafari && safariVersion ? parseInt(safariVersion, 10) < 15 : false;
+    return {
+        mp3: !!(!isOldOpera && (mpegTest || audioTest.canPlayType('audio/mp3;'))),
+        mpeg: mpegTest,
+        opus: !!audioTest.canPlayType('audio/ogg; codecs="opus"'),
+        ogg: !!audioTest.canPlayType('audio/ogg; codecs="vorbis"'),
+        oga: !!audioTest.canPlayType('audio/ogg; codecs="vorbis"'),
+        wav: !!(audioTest.canPlayType('audio/wav; codecs="1"') || audioTest.canPlayType('audio/wav')),
+        aac: !!audioTest.canPlayType('audio/aac;'),
+        caf: !!audioTest.canPlayType('audio/x-caf;'),
+        m4a: !!(audioTest.canPlayType('audio/x-m4a;') ||
+            audioTest.canPlayType('audio/m4a;') ||
+            audioTest.canPlayType('audio/aac;')),
+        m4b: !!(audioTest.canPlayType('audio/x-m4b;') ||
+            audioTest.canPlayType('audio/m4b;') ||
+            audioTest.canPlayType('audio/aac;')),
+        mp4: !!(audioTest.canPlayType('audio/x-mp4;') ||
+            audioTest.canPlayType('audio/mp4;') ||
+            audioTest.canPlayType('audio/aac;')),
+        weba: !!(!isOldSafari && audioTest.canPlayType('audio/webm; codecs="vorbis"')),
+        webm: !!(!isOldSafari && audioTest.canPlayType('audio/webm; codecs="vorbis"')),
+        dolby: !!audioTest.canPlayType('audio/mp4; codecs="ec-3"'),
+        flac: !!(audioTest.canPlayType('audio/x-flac;') || audioTest.canPlayType('audio/flac;')),
+    };
+}
+/* node:coverage enable */
+const supportedCodecs = readCodecs();
+/**
+ * An enum of audio codec names.
+ *
+ * @category Internal
+ */
+export const Codec = mapObjectValues(supportedCodecs, (key) => key);
+/**
+ * Check if the given audio codec/extension is supported in the current browser.
+ *
+ * @category Internal
+ */
+// eslint-disable-next-line sonarjs/prefer-type-guard
+export function isCodecSupported(codec) {
+    return !!supportedCodecs[codec];
+}
+/**
+ * Check if the given audio file is supported in the current browser by extracting its file
+ * extension.
+ *
+ * @category Internal
+ */
+export function isFileSupported(fileName) {
+    const fileExtension = extractFileExtension(fileName);
+    if (!fileExtension) {
+        throw new Error(`Cannot determine file extension from '${fileName}'`);
+    }
+    return isCodecSupported(fileExtension);
+}
+function extractFileExtension(fileName) {
+    // Extract the file extension from the URL or base64 data URI.
+    const fromBase64DataUri = /^data:audio\/([^;,]+);/i.exec(fileName);
+    const preSearch = fileName.split('?', 1)[0];
+    const fromUrl = preSearch && /\.([^.]+)$/.exec(preSearch);
+    const finalValue = fromBase64DataUri || fromUrl;
+    return finalValue?.[1]?.toLowerCase();
+}

package/dist/detect-play.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Detects if the browser session currently supports playing audio.
+ *
+ * @category Internal
+ */
+export declare function isPlayingEnabled(audioContext?: Readonly<BaseAudioContext>): Promise<boolean>;

package/dist/detect-play.js

@@ -0,0 +1,29 @@
+import { DeferredPromise } from '@augment-vir/common';
+/**
+ * Detects if the browser session currently supports playing audio.
+ *
+ * @category Internal
+ */
+export async function isPlayingEnabled(audioContext = new AudioContext()) {
+    /** Firefox requires an explicit resume after user gesture; other browsers auto-resume. */
+    if (audioContext instanceof AudioContext && audioContext.state === 'suspended') {
+        audioContext.resume().catch(() => { });
+    }
+    const source = audioContext.createBufferSource();
+    source.buffer = audioContext.createBuffer(1, 1, 22_050);
+    source.connect(audioContext.destination);
+    const deferredPromise = new DeferredPromise();
+    source.addEventListener('ended', () => {
+        source.disconnect();
+        if (!deferredPromise.isSettled) {
+            deferredPromise.resolve(true);
+        }
+    });
+    source.start();
+    globalThis.setTimeout(() => {
+        if (!deferredPromise.isSettled) {
+            deferredPromise.resolve(false);
+        }
+    }, 100);
+    return deferredPromise.promise;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './antha-audio.mod.js';
+export * from './audio-file.js';
+export * from './audio-player.js';
+export * from './codecs.js';
+export * from './detect-play.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './antha-audio.mod.js';
+export * from './audio-file.js';
+export * from './audio-player.js';
+export * from './codecs.js';
+export * from './detect-play.js';

package/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "@antha/audio",
+    "version": "0.0.1",
+    "description": "An Antha mod for handling audio.",
+    "keywords": [
+        "vir",
+        "antha",
+        "audio"
+    ],
+    "homepage": "https://github.com/electrovir/antha",
+    "bugs": {
+        "url": "https://github.com/electrovir/antha/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/electrovir/antha.git"
+    },
+    "license": "(MIT OR CC0-1.0)",
+    "author": {
+        "name": "electrovir",
+        "url": "https://github.com/electrovir"
+    },
+    "sideEffects": false,
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "test": "virmator test web",
+        "test:coverage": "npm test coverage",
+        "test:docs": "virmator docs check"
+    },
+    "dependencies": {
+        "@augment-vir/assert": "^31.73.1",
+        "@augment-vir/common": "^31.73.1"
+    },
+    "devDependencies": {
+        "@antha/engine": "*",
+        "@augment-vir/test": "^31.73.1",
+        "@web/dev-server-esbuild": "^1.0.5",
+        "@web/test-runner": "^0.20.2",
+        "@web/test-runner-playwright": "^0.11.1",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "typed-event-target": "^4.3.1"
+    },
+    "peerDependencies": {
+        "@antha/engine": "*",
+        "element-vir": ">=26",
+        "typed-event-target": ">4.3"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}