feat(pencil): add custom events

Author: AbreezaSaleem

.releaserc

@@ -14,8 +14,6 @@
         ],
         "message": "chore: Release \\${nextRelease.version} [skip ci]\n\n\\${nextRelease.notes}"
     }],
-    ["@semantic-release/npm", {
-      "tarballDir": "./dist"
-    }]
+    ["@semantic-release/npm"]
   ]
 }

README.md

@@ -7,7 +7,7 @@
 
 Say goodbye to boring audio elments and hello to interactive voice recording! `react-voice-recorder-player` is a React component that lets users record and playback their voice directly in the browser. It even includes a waveform graph that shows the audio being captured and played back in real-time.
 
-`react-voice-recorder-player` is an ultra light-weight component. The package size is only `164 kB` meaning it won't add unnecessary bulk to your application. And the best part is, its completely customizable! You can easily change the appearance of the component to fit your application's unique design.
+`react-voice-recorder-player` is an ultra light-weight component. The package size is only around `160 kB` meaning it won't add unnecessary bulk to your application. And the best part is, its completely customizable! You can easily change the appearance of the component to fit your application's unique design and trigger your own code on our custom events.
 
 ## Installation
 
@@ -70,6 +70,19 @@ The `VoiceRecorder` component will provide your users with an intuitive MP3-like
 | `onAudioDownload`            | A callback function that'll get called as soon as the `Blob` is available. | `Function`         |
 ------------------------------------------------------------------------------------------------------------------------------------------
 
+## Custom Events
+In addition to the props mentioned above, you can also use our custom callback events to trigger specific actions in your application. Here's a list of the custom events that are available:
+
+| Prop name        | Description                               | Type        |
+|------------------|-------------------------------------------|-------------|
+| `onRecordingStart` | Event triggered when recording starts      | `function`  |
+| `onRecordingEnd`   | Event fired when recording ends            | `function`  |
+| `onPlayStart`      | Event triggered when playback starts       | `function`  |
+| `onPlayEnd`        | Event fired when playback ends             | `function`  |
+| `onRecordingPause` | Event triggered when recording is paused   | `function`  |
+| `onPlayPause`      | Event fired when playback is paused        | `function`  |
+
+
 ## Customization
 
 Want to make the `VoiceRecorder` component even more personalized? No problem! You can customize the appearance of the component by passing in your own style objects. Here's an example:

dist/react-voice-recorder-player.js

@@ -1,6 +1,6 @@
 {
   "name": "react-voice-recorder-player",
-  "version": "1.0.10",
+  "version": "1.1.12",
   "description": "Voice Recorder Component for React",
   "repository": {
     "type": "git",

dist/react-voice-recorder-player.umd.cjs

@@ -1,7 +1,7 @@
 /* eslint-disable jsx-a11y/anchor-is-valid */
 /* eslint-disable jsx-a11y/anchor-has-content */
 /// <reference types="vite-plugin-svgr/client" /> // this imports the vite-plugin-svgr declaration file
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useRef } from 'react';
 import { useAudio, useUserProps } from '../../context';
 import { ReactComponent as Pause } from '../../assets/pause.svg';
 import { ReactComponent as Play } from '../../assets/play.svg';
@@ -20,12 +20,18 @@ const INITIAL_BUTTON_STATUSES = {
 };
 
 function Controllers() {
+  const downloadButtonRef = useRef<HTMLAnchorElement | null>(null);
   const { audioStatus, updateAudioStatus, audioRecording } = useAudio();
   const {
       controllerContainerStyle,
       controllerStyle,
-      downloadable,
+      downloadable = true,
       onAudioDownload,
+      onRecordingStart,
+      onPlayStart,
+      onRecordingPause,
+      onPlayPause,
+      rootElementId,
     } = useUserProps();
   const [buttonStatuses, setButtonStatuses] = useState<Record<string, boolean>>(INITIAL_BUTTON_STATUSES);
 
@@ -53,26 +59,26 @@ function Controllers() {
     .then(updateAudio(RECORDING)).catch(() => alert('Please allow acccess to your microphone to continue.'));
   }
 
-  useEffect(() => {
-    const maincontainer = document.querySelector('.voice-recorder_maincontainer')  as HTMLElement;
-    const controlcontainer = document.querySelector('.voice-recorder_controlscontainer') as HTMLElement;
-
-    if (maincontainer && controlcontainer) {
-      const { height } = maincontainer.getBoundingClientRect();
-      controlcontainer.style.height = `${height / 3}px`;
-    }
-  }, []);
-
   const downloadBlob = () => {
     const { blob = '' } = audioRecording || {};
-    if (!blob) return null;
-    const url = URL.createObjectURL(blob);  
-    const aElem = document.querySelector('.voice-recorder_downloadfile') as HTMLAnchorElement;
-    aElem.href = url;
-    aElem.download = 'audio.wav';
-    aElem.click();
+    if (!blob || !downloadButtonRef.current) return null;
+    const url = URL.createObjectURL(blob);
+    downloadButtonRef.current.href = url;
+    downloadButtonRef.current.download = 'audio.wav';
+    downloadButtonRef.current.click();
   };
 
+  useEffect(() => {
+    const rootElement = document.getElementById(rootElementId) as HTMLElement;
+    if (rootElement) {
+      const controlcontainer = rootElement.querySelector('.voice-recorder_controlscontainer') as HTMLElement;
+      if (rootElement && controlcontainer) {
+        const { height } = rootElement.getBoundingClientRect();
+        controlcontainer.style.height = `${height / 3}px`;
+      }
+    }
+  }, []);
+
   useEffect(() => {
     if (audioRecording) {
       const { blob = '' } = audioRecording || {};
@@ -89,37 +95,53 @@ function Controllers() {
           showRecordBtn: true,
         });
         break;
-      case RECORDING:
+      case RECORDING: {
+        onRecordingStart?.();
         setButtonStatuses({
           ...INITIAL_BUTTON_STATUSES,
           showPauseBtn: true,
           showStopBtn: true,
         });
         break;
-      case PAUSED_RECORDING:
+      }
+      case PAUSED_RECORDING: {
+        onRecordingPause?.();
         setButtonStatuses({
           ...INITIAL_BUTTON_STATUSES,
           showStopBtn: true,
           showRecordBtn: true,
         });
         break;
-      case PAUSED_PLAYING:
+      }
+      case PAUSED_PLAYING: {
+        onPlayPause?.();
         setButtonStatuses({
           ...INITIAL_BUTTON_STATUSES,
           showPlayBtn: true,
           showPauseBtn: true,
           showRedoBtn: true,
         });
         break;
-      case PLAYING:
-      case STOPPED:
+      }
+      case PLAYING: {
+        onPlayStart?.();
+        setButtonStatuses({
+          ...INITIAL_BUTTON_STATUSES,
+          showPauseBtn: true,
+          showPlayBtn: true,
+          showRedoBtn: true,
+        });
+        break;
+      }
+      case STOPPED: {
         setButtonStatuses({
           ...INITIAL_BUTTON_STATUSES,
           showPauseBtn: true,
           showPlayBtn: true,
           showRedoBtn: true,
         });
         break;
+      }
       default:
         setButtonStatuses(INITIAL_BUTTON_STATUSES);
     }
@@ -171,7 +193,7 @@ function Controllers() {
           })}
         </div>
       </div>
-      <a download style={{display: "none"}} className="voice-recorder_downloadfile" />
+      <a ref={downloadButtonRef} download style={{display: "none"}} className="voice-recorder_downloadfile" />
     </div>
   )
 }

package.json

@@ -8,7 +8,7 @@ const BUFFER_VS_HTML_DURATION_DIFFERENCE = 0.06;
 function Playback() {
   const [adjustedBars, setAdjustedBars] = useState<GraphDataType[]>([]);
   const { audioRecording, audioStatus, updateAudioStatus } = useAudio();
-  const { graphColor, graphShaded } = useUserProps();
+  const { graphColor, graphShaded, rootElementId, onPlayEnd } = useUserProps();
   const unplayedCanvasRef = useRef<HTMLCanvasElement | null>(null);
   const playedCanvasRef = useRef<HTMLCanvasElement | null>(null);
   const progressLineRef = useRef<HTMLCanvasElement  | null>(null);
@@ -64,21 +64,24 @@ function Playback() {
   };
 
   const setUpCanvas = () => {
-    const canvasElements = setUpCanvasUtil([
+    const canvasElements = setUpCanvasUtil(
+    rootElementId,
+    [
       'waveformgraph-unplayed-graph',
       'waveformgraph-played-graph',
       'progressbar',
     ], '.voice-recorder_canvascontainer');
 
-    unplayedCanvasRef.current = canvasElements?.find((elem) => elem.id === 'waveformgraph-unplayed-graph') as HTMLCanvasElement;
-    playedCanvasRef.current = canvasElements?.find((elem) => elem.id === 'waveformgraph-played-graph') as HTMLCanvasElement;
-    progressLineRef.current = canvasElements?.find((elem) => elem.id === 'progressbar') as HTMLCanvasElement;
+    unplayedCanvasRef.current = canvasElements?.find((elem) => elem.className === 'waveformgraph-unplayed-graph') as HTMLCanvasElement;
+    playedCanvasRef.current = canvasElements?.find((elem) => elem.className === 'waveformgraph-played-graph') as HTMLCanvasElement;
+    progressLineRef.current = canvasElements?.find((elem) => elem.className === 'progressbar') as HTMLCanvasElement;
   }
 
   const pauseAudio = () => audioRef?.current?.pause();
 
   const playAudio = () => {
-    const audioELem = document.querySelector('#playback_audio') as HTMLAudioElement;
+    const rootElement = document.getElementById(rootElementId) as HTMLElement;
+    const audioELem = rootElement.querySelector('#playback_audio') as HTMLAudioElement;
     audioELem.autoplay = true;
     /* play from start */
     if (audioELem.readyState !== 4) {
@@ -100,6 +103,7 @@ function Playback() {
       }
     }
     audioELem.onended = () => {
+      if (blob) onPlayEnd?.(blob);
       updateAudioStatus(STOPPED);
     }
   };

src/components/controllers/index.tsx

@@ -13,7 +13,7 @@ const GRAPH_WIDTH = 2;
 
 function Record() {
   const { audioStatus = '', updateAudioRecording } = useAudio();
-  const { graphColor, graphShaded } = useUserProps();
+  const { graphColor, graphShaded, rootElementId, onRecordingEnd } = useUserProps();
   const [now, setNow] = useState<number>(0);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const obj = useRef<CanvasObj>({});
@@ -48,7 +48,7 @@ function Record() {
   }, []);
 
   const setUpCanvas = () => {
-    const canvas = setUpCanvasUtil(['waveformgraph-record'], '.voice-recorder_recordcontainer')
+    const canvas = setUpCanvasUtil(rootElementId, ['waveformgraph-record'], '.voice-recorder_recordcontainer');
 
     if (canvas) canvasRef.current = canvas[0];
   };
@@ -90,6 +90,7 @@ function Record() {
         const arrayBuffer = await event.data.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
         const recordingData = { blob: event.data, duration: audioBuffer.duration, graphData: (obj.current.graphData ?? []) }
+        onRecordingEnd?.(event.data);
         updateAudioRecording(recordingData);
       });
       mediaRecorder.addEventListener('stop', () => {
@@ -124,7 +125,7 @@ function Record() {
 
       maxFreq = Math.max(0, ...obj?.current?.dataArray ?? [])
 
-      const freq = Math.max(1, Math.floor(maxFreq * 350));
+      const freq = Math.max(1, Math.floor(maxFreq * 550));
 
       if (obj.current.graphData === undefined) {
         obj.current.graphData = [];

src/components/waveform/playback.tsx

@@ -11,6 +11,13 @@ const UserPropsContext = createContext<UserPropsContextInterface>({
   width: 'inherit',
   downloadable: false,
   onAudioDownload: () => undefined,
+  onRecordingStart: () => undefined,
+  onRecordingEnd: () => undefined,
+  onPlayStart: () => undefined,
+  onPlayEnd: () => undefined,
+  onRecordingPause: () => undefined,
+  onPlayPause: () => undefined,
+  rootElementId: '',
 });
 
 function UserPropsProvider({ userPropsValue, children } :

src/components/waveform/record.tsx

@@ -42,7 +42,7 @@
     position: relative;
     height: 100%;
 
-    #progressbar, #waveformgraph-played-graph {
+    .progressbar, .waveformgraph-played-graph {
       position: absolute;
       left: 0;
     }