@aippy/runtime 0.1.0 → 0.2.0-dev.1

package/README.md

@@ -66,11 +66,33 @@ await pwa.registerServiceWorker('/sw.js');
 await pwa.sendNotification('Hello!');
 ```
 
+### Audio (iOS Silent Mode Compatible)
+
+```typescript
+import { patchAudioContext } from '@aippy/runtime/audio';
+
+// Create and patch AudioContext to bypass iOS silent mode
+const ctx = new AudioContext();
+const patchedCtx = patchAudioContext(ctx);
+
+// Unlock audio on user interaction (required on iOS)
+button.onclick = async () => {
+  await patchedCtx.unlock();
+  
+  // Use native Web Audio API as normal
+  const osc = patchedCtx.createOscillator();
+  osc.connect(patchedCtx.destination);
+  osc.start();
+  osc.stop(patchedCtx.currentTime + 1);
+};
+```
+
 ## Packages
 
 - `@aippy/runtime/core` - Core types and configuration
 - `@aippy/runtime/device` - Device APIs (camera, geolocation, sensors, file system)
 - `@aippy/runtime/utils` - Platform detection, performance monitoring, PWA utilities
+- `@aippy/runtime/audio` - iOS-compatible Web Audio API wrapper
 
 ## Publishing
 

package/dist/audio/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Audio module for iOS-compatible Web Audio API
+ *
+ * This module provides utilities to bypass iOS silent mode restrictions
+ * on Web Audio API playback.
+ *
+ * @module @aippy/runtime/audio
+ */
+export { patchAudioContext } from './patchAudioContext';
+export type { AudioContextPatchOptions, MediaElementType, PatchedAudioContext, } from './types';
+export { createHiddenMediaElement, createHiddenVideoElement, isIOSDevice, isMediaStreamAudioSupported, } from './utils';
+export { useAudioContext } from './useAudioContext';
+export type { UseAudioContextOptions, UseAudioContextReturn } from './useAudioContext';

package/dist/audio/index.js

@@ -0,0 +1,9 @@
+import { c, a, i, b, p, u } from "../useAudioContext-DSbHyklm.js";
+export {
+  c as createHiddenMediaElement,
+  a as createHiddenVideoElement,
+  i as isIOSDevice,
+  b as isMediaStreamAudioSupported,
+  p as patchAudioContext,
+  u as useAudioContext
+};

package/dist/audio/patchAudioContext.d.ts

@@ -0,0 +1,30 @@
+import { AudioContextPatchOptions, PatchedAudioContext } from './types';
+/**
+ * Patches an AudioContext to bypass iOS silent mode restrictions
+ *
+ * On iOS devices, Web Audio API is affected by the hardware silent switch.
+ * This function routes audio through a MediaStreamAudioDestinationNode
+ * connected to a hidden video element, which bypasses the restriction.
+ *
+ * On non-iOS devices, this function returns the original context with
+ * minimal modifications (zero overhead).
+ *
+ * @param audioContext - The AudioContext to patch
+ * @param options - Configuration options
+ * @returns Enhanced AudioContext with iOS compatibility
+ *
+ * @example
+ * ```typescript
+ * const ctx = new AudioContext();
+ * const patchedCtx = patchAudioContext(ctx);
+ *
+ * // Unlock on user interaction (iOS only)
+ * button.onclick = () => patchedCtx.unlock();
+ *
+ * // Use native Web Audio API normally
+ * const osc = patchedCtx.createOscillator();
+ * osc.connect(patchedCtx.destination); // Auto-routed on iOS
+ * osc.start();
+ * ```
+ */
+export declare function patchAudioContext(audioContext: AudioContext, options?: AudioContextPatchOptions): PatchedAudioContext;

package/dist/audio/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Media element type for MediaStream playback
+ */
+export type MediaElementType = 'video' | 'audio';
+/**
+ * Options for patching AudioContext
+ */
+export interface AudioContextPatchOptions {
+    /**
+     * Force enable patching even on non-iOS devices
+     * @default false
+     */
+    forceEnable?: boolean;
+    /**
+     * Automatically cleanup media element when AudioContext is closed
+     * @default true
+     */
+    autoCleanup?: boolean;
+    /**
+     * Show media element for debugging purposes
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Media element type to use for MediaStream playback
+     * Note: 'video' is recommended for better iOS compatibility
+     * @default 'video'
+     */
+    mediaElementType?: MediaElementType;
+}
+/**
+ * Extended AudioContext with iOS compatibility features
+ */
+export interface PatchedAudioContext extends AudioContext {
+    /**
+     * Unlock audio playback on iOS (must be called in user interaction)
+     * @returns Promise that resolves when unlocked
+     */
+    unlock(): Promise<void>;
+    /**
+     * Manually cleanup patched resources
+     */
+    cleanup(): void;
+    /**
+     * Indicates whether the context has been patched
+     */
+    readonly isPatched: boolean;
+    /**
+     * Reference to the original AudioDestinationNode
+     */
+    readonly originalDestination: AudioDestinationNode;
+}

package/dist/audio/useAudioContext.d.ts

@@ -0,0 +1,66 @@
+import { PatchedAudioContext, AudioContextPatchOptions } from './types';
+/**
+ * Options for useAudioContext hook
+ */
+export interface UseAudioContextOptions extends AudioContextPatchOptions {
+    /**
+     * Auto-unlock audio on first user interaction
+     * @default true
+     */
+    autoUnlock?: boolean;
+}
+/**
+ * Return type for useAudioContext hook
+ */
+export interface UseAudioContextReturn {
+    /**
+     * Patched AudioContext instance
+     */
+    audioContext: PatchedAudioContext | null;
+    /**
+     * Whether audio has been unlocked (ready for playback)
+     */
+    isUnlocked: boolean;
+    /**
+     * Manually unlock audio (call during user interaction)
+     */
+    unlock: () => Promise<void>;
+}
+/**
+ * React hook for managing AudioContext lifecycle with iOS silent mode bypass
+ *
+ * Automatically handles:
+ * - AudioContext creation and patching
+ * - Cleanup on unmount
+ * - Optional auto-unlock on first user interaction
+ *
+ * Note: Built for React 19 - no useCallback needed for optimal performance
+ *
+ * @param options - Configuration options
+ * @returns AudioContext instance, unlock status, and unlock function
+ *
+ * @example
+ * ```tsx
+ * function AudioComponent() {
+ *   const { audioContext, isUnlocked, unlock } = useAudioContext();
+ *
+ *   const playSound = async () => {
+ *     if (!audioContext) return;
+ *
+ *     // Unlock if needed (handles iOS restrictions)
+ *     if (!isUnlocked) {
+ *       await unlock();
+ *     }
+ *
+ *     // Play sound using Web Audio API
+ *     const osc = audioContext.createOscillator();
+ *     osc.connect(audioContext.destination);
+ *     osc.start();
+ *     osc.stop(audioContext.currentTime + 0.3);
+ *   };
+ *
+ *   return <button onClick={playSound}>Play Sound</button>;
+ * }
+ * ```
+ */
+export declare function useAudioContext(options?: UseAudioContextOptions): UseAudioContextReturn;

package/dist/audio/utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Detects if the current device is running iOS/iPadOS
+ * @returns true if device is iOS/iPadOS
+ */
+export declare function isIOSDevice(): boolean;
+/**
+ * Checks if MediaStreamAudioDestinationNode is supported by the browser
+ * @returns true if supported
+ */
+export declare function isMediaStreamAudioSupported(): boolean;
+/**
+ * Creates a hidden media element for MediaStream playback
+ * @param type - Element type ('video' or 'audio')
+ * @param debug - If true, makes the element visible for debugging
+ * @returns HTMLMediaElement (HTMLVideoElement or HTMLAudioElement)
+ */
+export declare function createHiddenMediaElement(type?: 'video' | 'audio', debug?: boolean): HTMLVideoElement | HTMLAudioElement;
+/**
+ * @deprecated Use createHiddenMediaElement instead
+ * Creates a hidden video element for MediaStream playback
+ * @param debug - If true, makes the video element visible for debugging
+ * @returns HTMLVideoElement
+ */
+export declare function createHiddenVideoElement(debug?: boolean): HTMLVideoElement;

package/dist/audio.d.ts

@@ -0,0 +1,2 @@
+export * from './audio/index'
+export {}

package/dist/core/index.js

@@ -33,7 +33,7 @@ function mergeConfig(userConfig) {
     }
   };
 }
-const version = "0.1.0";
+const version = "0.2.0-dev.1";
 const packageJson = {
   version
 };

package/dist/index/index.js

@@ -3,6 +3,7 @@ import { A, E, c } from "../errors-DAz5_jDJ.js";
 import { CameraAPI, FileSystemAPI, GeolocationAPI, SensorsAPI, camera, fileSystem, geolocation, sensors, vibrate } from "../device/index.js";
 import { c as c2, a, P, b, p, d } from "../pwa-BkviTQoN.js";
 import { a as a2, b as b2 } from "../useTweaks-mK5PAWOs.js";
+import { c as c3, a as a3, i, b as b3, p as p2, u } from "../useAudioContext-DSbHyklm.js";
 export {
   A as AippyRuntimeError,
   CameraAPI,
@@ -20,14 +21,20 @@ export {
   b2 as aippyTweaksRuntime,
   camera,
   c as createError,
+  c3 as createHiddenMediaElement,
+  a3 as createHiddenVideoElement,
   fileSystem,
   geolocation,
   getConfigFromEnv,
   getVersionInfo,
+  i as isIOSDevice,
+  b3 as isMediaStreamAudioSupported,
   mergeConfig,
+  p2 as patchAudioContext,
   b as performanceMonitor,
   p as platform,
   d as pwa,
   sensors,
+  u as useAudioContext,
   vibrate
 };

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './core';
 export * from './device';
 export * from './utils';
 export * from './tweaks';
+export * from './audio';

package/dist/tweaks/types.d.ts

@@ -0,0 +1,52 @@
+declare global {
+    interface Window {
+        aippyTweaksRuntime?: {
+            tweaks: (config: any) => any;
+            tweaksInstance?: Record<string, any>;
+        };
+        processNativeData?: (data: any) => void;
+    }
+    interface WebKit {
+        messageHandlers: {
+            aippyListener: {
+                postMessage: (data: any) => void;
+            };
+        };
+    }
+}
+export interface TweakItem {
+    id: string;
+    index: number;
+    name: string;
+    description: string;
+    group?: string;
+    type: 'number' | 'color' | 'boolean' | 'text' | 'image';
+    value: number | string | boolean;
+}
+export interface NumberTweakItem extends TweakItem {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+    value: number;
+}
+export interface BooleanTweakItem extends TweakItem {
+    type: 'boolean';
+    value: boolean;
+}
+export interface TextTweakItem extends TweakItem {
+    type: 'text';
+    value: string;
+}
+export interface ColorTweakItem extends TweakItem {
+    type: 'color';
+    value: string;
+}
+export interface ImageTweakItem extends TweakItem {
+    type: 'image';
+    value: string;
+}
+export type TweakConfig = NumberTweakItem | BooleanTweakItem | TextTweakItem | ColorTweakItem | ImageTweakItem;
+export interface TweaksConfig {
+    [key: string]: TweakConfig;
+}

package/dist/useAudioContext-DSbHyklm.js

@@ -0,0 +1,186 @@
+import { useRef, useEffect } from "react";
+function isIOSDevice() {
+  const userAgent = navigator.userAgent;
+  if (/iPad|iPhone|iPod/.test(userAgent)) {
+    return true;
+  }
+  if (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1) {
+    return true;
+  }
+  return false;
+}
+function isMediaStreamAudioSupported() {
+  try {
+    if (!window.AudioContext) {
+      return false;
+    }
+    const tempContext = new AudioContext();
+    const hasMethod = typeof tempContext.createMediaStreamDestination === "function";
+    tempContext.close();
+    return hasMethod;
+  } catch {
+    return false;
+  }
+}
+function createHiddenMediaElement(type = "video", debug = false) {
+  const element = document.createElement(type);
+  element.muted = false;
+  element.autoplay = true;
+  if (type === "video") {
+    element.playsInline = true;
+  }
+  if (debug) {
+    element.style.cssText = "position:fixed;bottom:10px;right:10px;width:200px;background:#ff0000;z-index:9999;";
+  } else {
+    element.style.cssText = "position:fixed;width:1px;height:1px;opacity:0;pointer-events:none;";
+  }
+  return element;
+}
+function createHiddenVideoElement(debug = false) {
+  return createHiddenMediaElement("video", debug);
+}
+function patchAudioContext(audioContext, options = {}) {
+  const {
+    forceEnable = false,
+    autoCleanup = true,
+    debug = false,
+    mediaElementType = "video"
+  } = options;
+  const needsPatch = forceEnable || isIOSDevice();
+  if (!needsPatch) {
+    return Object.assign(audioContext, {
+      unlock: async () => {
+        if (audioContext.state === "suspended") {
+          await audioContext.resume();
+        }
+      },
+      cleanup: () => {
+      },
+      isPatched: false,
+      originalDestination: audioContext.destination
+    });
+  }
+  if (!isMediaStreamAudioSupported()) {
+    console.warn(
+      "[AudioContext] MediaStreamAudioDestinationNode not supported, falling back to native"
+    );
+    return Object.assign(audioContext, {
+      unlock: async () => audioContext.resume(),
+      cleanup: () => {
+      },
+      isPatched: false,
+      originalDestination: audioContext.destination
+    });
+  }
+  const originalDestination = audioContext.destination;
+  const streamDestination = audioContext.createMediaStreamDestination();
+  const mediaElement = createHiddenMediaElement(mediaElementType, debug);
+  mediaElement.srcObject = streamDestination.stream;
+  document.body.appendChild(mediaElement);
+  Object.defineProperty(audioContext, "destination", {
+    get: () => streamDestination,
+    enumerable: true,
+    configurable: true
+  });
+  if (!("maxChannelCount" in streamDestination)) {
+    Object.defineProperty(streamDestination, "maxChannelCount", {
+      get: () => originalDestination.maxChannelCount,
+      enumerable: true
+    });
+  }
+  let isUnlocked = false;
+  const unlock = async () => {
+    if (isUnlocked) {
+      return;
+    }
+    try {
+      await mediaElement.play();
+      if (audioContext.state === "suspended") {
+        await audioContext.resume();
+      }
+      isUnlocked = true;
+      if (debug) {
+        console.log("[AudioContext] iOS unlock successful");
+      }
+    } catch (error) {
+      console.error("[AudioContext] Unlock failed:", error);
+      throw error;
+    }
+  };
+  const cleanup = () => {
+    try {
+      mediaElement.pause();
+      mediaElement.srcObject = null;
+      mediaElement.remove();
+      if (debug) {
+        console.log("[AudioContext] Cleanup completed");
+      }
+    } catch (error) {
+      console.error("[AudioContext] Cleanup error:", error);
+    }
+  };
+  if (autoCleanup) {
+    const originalClose = audioContext.close.bind(audioContext);
+    audioContext.close = async () => {
+      cleanup();
+      return originalClose();
+    };
+  }
+  return Object.assign(audioContext, {
+    unlock,
+    cleanup,
+    isPatched: true,
+    originalDestination
+  });
+}
+function useAudioContext(options = {}) {
+  const { autoUnlock = true, ...patchOptions } = options;
+  const audioContextRef = useRef(null);
+  const isUnlockedRef = useRef(false);
+  const unlockFnRef = useRef(null);
+  useEffect(() => {
+    const ctx = new AudioContext();
+    audioContextRef.current = patchAudioContext(ctx, patchOptions);
+    return () => {
+      audioContextRef.current?.cleanup();
+      audioContextRef.current?.close();
+    };
+  }, []);
+  if (!unlockFnRef.current) {
+    unlockFnRef.current = async () => {
+      const ctx = audioContextRef.current;
+      if (!ctx || isUnlockedRef.current) return;
+      try {
+        await ctx.unlock();
+        isUnlockedRef.current = true;
+      } catch (error) {
+        console.warn("Failed to unlock audio:", error);
+      }
+    };
+  }
+  useEffect(() => {
+    if (!autoUnlock) return;
+    const handleInteraction = async () => {
+      await unlockFnRef.current?.();
+    };
+    document.addEventListener("click", handleInteraction, { once: true });
+    document.addEventListener("touchstart", handleInteraction, { once: true });
+    return () => {
+      document.removeEventListener("click", handleInteraction);
+      document.removeEventListener("touchstart", handleInteraction);
+    };
+  }, [autoUnlock]);
+  return {
+    audioContext: audioContextRef.current,
+    isUnlocked: isUnlockedRef.current,
+    unlock: unlockFnRef.current
+  };
+}
+export {
+  createHiddenVideoElement as a,
+  isMediaStreamAudioSupported as b,
+  createHiddenMediaElement as c,
+  isIOSDevice as i,
+  patchAudioContext as p,
+  useAudioContext as u
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aippy/runtime",
-  "version": "0.1.0",
+  "version": "0.2.0-dev.1",
   "description": "Aippy Runtime SDK - Runtime SDK for Aippy projects",
   "private": false,
   "type": "module",
@@ -27,6 +27,10 @@
     "./tweaks": {
       "import": "./dist/tweaks/index.js",
       "types": "./dist/tweaks/index.d.ts"
+    },
+    "./audio": {
+      "import": "./dist/audio/index.js",
+      "types": "./dist/audio/index.d.ts"
     }
   },
   "files": [