@m2c2kit/core 0.3.26 → 0.3.27

package/dist/index.d.ts

@@ -4739,10 +4739,49 @@ declare class SoundRecorder extends M2Node implements Omit<SoundRecorderOptions,
      */
     constructor(options?: SoundRecorderOptions);
     initialize(): void;
+    /**
+     * Starts recording audio from the microphone.
+     *
+     * @remarks If the `SoundRecorder` is already recording, an error will be
+     * thrown. If permission to use the microphone has not been granted, the
+     * browser will prompt the user to allow or deny access. Denial of access
+     * will result in an error being thrown. To avoid this, use the
+     * `queryPermission()` and `requestPermission()` methods to check and request
+     * permission, respectively, and handle the results accordingly.
+     */
     start(): Promise<void>;
+    /**
+     * Stops recording audio from the microphone.
+     *
+     * @remarks If the `stop()` method is not awaited, the method returns a
+     * Promise and the useable data will be lost.
+     *
+     * @returns A promise that resolves to a {@link SoundRecorderResults} object.
+     * The `audioBase64` property of the object contains the recorded audio as a
+     * base64 string.
+     */
     stop(): Promise<SoundRecorderResults>;
     pause(): void;
     resume(): void;
+    /**
+     * Checks if the microphone permission is granted.
+     *
+     * @remarks This does not request permission from the user. It only queries
+     * the current microphone permission state.
+     *
+     * @returns The `state` property ("granted", "denied", or "prompt") of
+     * `PermissionStatus` or undefined if the browser does not support the
+     * "microphone" permission.
+     * See https://developer.mozilla.org/en-US/docs/Web/API/PermissionStatus/state
+     */
+    queryPermission(): Promise<string | undefined>;
+    /**
+     * Requests permission to use the microphone, and possibly prompts the user
+     * to allow or deny access.
+     *
+     * @returns true if the microphone permission is granted, false if denied.
+     */
+    requestPermission(): Promise<boolean>;
     /** Is the `SoundRecorder` currently recording? */
     get isRecording(): boolean;
     /** Is the `SoundRecorder` currently paused? */

package/dist/index.js

@@ -11855,12 +11855,24 @@ class SoundRecorder extends M2Node {
   }
   initialize() {
   }
+  /**
+   * Starts recording audio from the microphone.
+   *
+   * @remarks If the `SoundRecorder` is already recording, an error will be
+   * thrown. If permission to use the microphone has not been granted, the
+   * browser will prompt the user to allow or deny access. Denial of access
+   * will result in an error being thrown. To avoid this, use the
+   * `queryPermission()` and `requestPermission()` methods to check and request
+   * permission, respectively, and handle the results accordingly.
+   */
   async start() {
     if (this.isRecording) {
       throw new Error(
         "cannot start SoundRecorder because it is already started."
       );
     }
+    this.audioChunks = [];
+    this.endIso8601Timestamp = void 0;
     const supportedMimeTypes = this.getMediaRecorderSupportedAudioMimeTypes();
     if (supportedMimeTypes.length === 0) {
       throw new Error(
@@ -11877,7 +11889,7 @@ class SoundRecorder extends M2Node {
         audio: this.audioTrackConstraints ? this.audioTrackConstraints : true
       });
     } catch (error) {
-      throw new Error("Error getting user media.");
+      throw new Error(`Error getting user media: ${error}.`);
     }
     if (!stream) {
       throw new Error("no stream.");
@@ -11900,6 +11912,16 @@ class SoundRecorder extends M2Node {
     this._isRecording = true;
     this._isPaused = false;
   }
+  /**
+   * Stops recording audio from the microphone.
+   *
+   * @remarks If the `stop()` method is not awaited, the method returns a
+   * Promise and the useable data will be lost.
+   *
+   * @returns A promise that resolves to a {@link SoundRecorderResults} object.
+   * The `audioBase64` property of the object contains the recorded audio as a
+   * base64 string.
+   */
   async stop() {
     if (!this.isRecording) {
       throw new Error("cannot stop SoundRecorder because it has not started.");
@@ -11959,6 +11981,52 @@ class SoundRecorder extends M2Node {
     this._isPaused = false;
     Timer.start(this.timerUuid);
   }
+  /**
+   * Checks if the microphone permission is granted.
+   *
+   * @remarks This does not request permission from the user. It only queries
+   * the current microphone permission state.
+   *
+   * @returns The `state` property ("granted", "denied", or "prompt") of
+   * `PermissionStatus` or undefined if the browser does not support the
+   * "microphone" permission.
+   * See https://developer.mozilla.org/en-US/docs/Web/API/PermissionStatus/state
+   */
+  async queryPermission() {
+    try {
+      const status = await navigator.permissions.query({
+        /**
+         * We use a type assertion here because the PermissionName type
+         * does not include "microphone" in the TypeScript type definitions.
+         */
+        name: "microphone"
+      });
+      return status.state;
+    } catch (error) {
+      console.warn(
+        `Error calling navigator.permissions.query({ name: "microphone" }): ${error}.`
+      );
+      return void 0;
+    }
+  }
+  /**
+   * Requests permission to use the microphone, and possibly prompts the user
+   * to allow or deny access.
+   *
+   * @returns true if the microphone permission is granted, false if denied.
+   */
+  async requestPermission() {
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: this.audioTrackConstraints ? this.audioTrackConstraints : true
+      });
+      stream.getTracks().forEach((track) => track.stop());
+      return true;
+    } catch (error) {
+      console.warn(`Microphone access denied: ${error}`);
+      return false;
+    }
+  }
   /** Is the `SoundRecorder` currently recording? */
   get isRecording() {
     return this._isRecording;
@@ -12112,7 +12180,7 @@ class Story {
   }
 }
 
-console.log("\u26AA @m2c2kit/core version 0.3.26 (8bba62e1)");
+console.log("\u26AA @m2c2kit/core version 0.3.27 (1ed4ac2a)");
 
 export { Action, ActivityType, CanvasKitHelpers, ColorfulMutablePath, Composite, Constants, ConstraintType, CustomAction, Dimensions, Easings, Equal, Equals, EventStore, EventStoreMode, FadeAlphaAction, FontManager, Game, GroupAction, I18n, ImageManager, Label, LabelHorizontalAlignmentMode, LayoutConstraint, LegacyTimer, M2EventType, M2ImageStatus, M2Node, M2NodeFactory, M2NodeType, M2SoundStatus, M2c2KitHelpers, MoveAction, MutablePath, NoneTransition, PlayAction, RandomDraws, RepeatAction, RepeatForeverAction, RotateAction, ScaleAction, Scene, SceneTransition, SequenceAction, Shape, ShapeType, SlideTransition, SoundManager, SoundPlayer, SoundRecorder, Sprite, Story, TextLine, Timer, Transition, TransitionDirection, TransitionType, Uuid, WaitAction, WebColors, WebGlInfo, handleInterfaceOptions };
 //# sourceMappingURL=index.js.map