react-media-manager 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arunkumarbrahmaniyaa
+
+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.

package/README.md

@@ -0,0 +1,195 @@
+# react-media-manager
+
+Production-ready React hooks for cameras, microphones, speakers, permissions, device changes, and recording. The package is SSR-safe, tree-shakeable, TypeScript-first, and built for React 18+ applications across Next.js, Vite, CRA, Remix, and plain React setups.
+
+## Features
+
+- Camera, microphone, and speaker device enumeration
+- Stream lifecycle management with start, stop, pause, resume, mute, and unmute flows
+- Permission querying and permission request helpers
+- Automatic device-change detection
+- Audio output switching through `setSinkId` when supported
+- Optional media recording hook
+- Human-readable normalized media errors
+- TypeScript declarations for all public hooks and device models
+
+## Installation
+
+```bash
+npm install react-media-manager
+```
+
+Peer dependencies:
+
+- `react >= 18`
+- `react-dom >= 18`
+
+## Quick Start
+
+```tsx
+import { useCamera } from 'react-media-manager';
+
+export function CameraPreview() {
+	const { cameras, currentCamera, stream, isActive, error, start, stop, switchCamera } = useCamera();
+
+	return (
+		<div>
+			<button onClick={() => void start()} disabled={isActive}>
+				Start camera
+			</button>
+			<button onClick={stop} disabled={!isActive}>
+				Stop camera
+			</button>
+			<select
+				value={currentCamera?.deviceId ?? ''}
+				onChange={(event) => void switchCamera(event.target.value)}
+			>
+				{cameras.map((camera) => (
+					<option key={camera.deviceId} value={camera.deviceId}>
+						{camera.label || camera.deviceId}
+					</option>
+				))}
+			</select>
+			{stream && <video autoPlay muted playsInline ref={(node) => node && (node.srcObject = stream)} />}
+			{error && <p>{error.message}</p>}
+		</div>
+	);
+}
+```
+
+## API Overview
+
+### `useCamera(options?)`
+
+Returns camera devices, the active stream, camera status, permission state, and camera controls.
+
+```ts
+const {
+	cameras,
+	currentCamera,
+	stream,
+	isActive,
+	isLoading,
+	isPaused,
+	permission,
+	status,
+	error,
+	start,
+	stop,
+	pause,
+	resume,
+	switchCamera,
+	refreshDevices,
+	refresh,
+	destroy,
+} = useCamera();
+```
+
+### `useMicrophone(options?)`
+
+Returns microphone devices, audio stream state, mute state, and live volume level monitoring when supported.
+
+### `useSpeaker(target)`
+
+Returns output devices and a `switchSpeaker` helper for `HTMLMediaElement.setSinkId` capable browsers.
+
+### `usePermissions()`
+
+Returns live camera and microphone permission state plus `requestCamera`, `requestMicrophone`, and `requestAll` helpers.
+
+### `useMediaDevices(options?)`
+
+Returns grouped device lists and a refresh method.
+
+### `useDeviceChange()`
+
+Returns refreshed devices plus `changeCount` and `lastChangeAt` each time `navigator.mediaDevices.devicechange` fires.
+
+### `useMediaRecorder()`
+
+Returns recorder lifecycle helpers, chunk data, final `Blob`, object URL, and download support.
+
+### `MediaProvider`
+
+Provides shared defaults:
+
+```tsx
+<MediaProvider
+	value={{
+		autoRefreshOnDeviceChange: true,
+		cameraConstraints: { width: 1280, height: 720 },
+		microphoneConstraints: { echoCancellation: true },
+		monitorMicrophoneVolume: true,
+	}}
+>
+	<App />
+</MediaProvider>
+```
+
+## TypeScript
+
+Public types include:
+
+- `CameraDevice`
+- `MicrophoneDevice`
+- `SpeakerDevice`
+- `MediaPermissionState`
+- `MediaError`
+- `MediaConstraints`
+
+## Browser Support
+
+- Chrome: supported
+- Edge: supported
+- Firefox: supported, with browser-specific output-device limitations
+- Safari: supported for core camera and microphone hooks, with limited output-device support
+- Brave: supported
+
+The library degrades gracefully when `MediaDevices`, `Permissions`, `MediaRecorder`, or `setSinkId` are not available.
+
+## Errors
+
+Errors are normalized into a consistent shape:
+
+```ts
+type MediaError = {
+	code:
+		| 'abort'
+		| 'browser-not-supported'
+		| 'device-in-use'
+		| 'device-not-found'
+		| 'invalid-state'
+		| 'not-allowed'
+		| 'not-readable'
+		| 'overconstrained'
+		| 'permission-denied'
+		| 'permission-query-failed'
+		| 'recorder-not-supported'
+		| 'speaker-not-supported'
+		| 'unknown';
+	message: string;
+	cause?: unknown;
+	name?: string;
+};
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Current local validation:
+
+- Build: passes with `tsup`
+- Tests: 16 passing
+- Coverage: 90.87% statements, 90.87% lines, 91.2% functions
+
+## Examples and Docs
+
+- JavaScript example: `examples/js-example/App.jsx`
+- TypeScript example: `examples/ts-example/App.tsx`
+- Next.js example notes: `docs/nextjs.md`
+- Troubleshooting and FAQ: `docs/troubleshooting.md`

package/dist/index.d.mts

@@ -0,0 +1,171 @@
+import React, { RefObject } from 'react';
+
+interface MediaProviderConfig {
+    autoRefreshOnDeviceChange?: boolean;
+    cameraConstraints?: MediaTrackConstraints;
+    microphoneConstraints?: MediaTrackConstraints;
+    monitorMicrophoneVolume?: boolean;
+}
+interface MediaProviderProps {
+    children: React.ReactNode;
+    value?: MediaProviderConfig;
+}
+declare function MediaProvider({ children, value }: MediaProviderProps): React.JSX.Element;
+declare function useMediaProviderConfig(): Required<MediaProviderConfig>;
+
+type HookPermissionState = PermissionState | 'unsupported' | 'unknown';
+type MediaPermissionState = HookPermissionState;
+type MediaDeviceCategory = 'camera' | 'microphone' | 'speaker';
+type MediaStatus = 'idle' | 'loading' | 'active' | 'paused' | 'stopped' | 'error';
+type MediaErrorCode = 'abort' | 'browser-not-supported' | 'device-in-use' | 'device-not-found' | 'invalid-state' | 'not-allowed' | 'not-readable' | 'overconstrained' | 'permission-denied' | 'permission-query-failed' | 'recorder-not-supported' | 'speaker-not-supported' | 'unknown';
+interface MediaError {
+    code: MediaErrorCode;
+    message: string;
+    cause?: unknown;
+    name?: string;
+}
+interface BaseMediaDevice<TKind extends MediaDeviceCategory = MediaDeviceCategory> {
+    deviceId: string;
+    groupId: string;
+    kind: TKind;
+    label: string;
+    raw: MediaDeviceInfo;
+}
+interface DeviceCollection {
+    cameras: BaseMediaDevice<'camera'>[];
+    microphones: BaseMediaDevice<'microphone'>[];
+    speakers: BaseMediaDevice<'speaker'>[];
+}
+interface BaseHookResult {
+    loading: boolean;
+    error: MediaError | null;
+    supported: boolean;
+    refresh: () => Promise<void>;
+    destroy: () => void;
+}
+interface MediaConstraints {
+    audio?: boolean | MediaTrackConstraints;
+    video?: boolean | MediaTrackConstraints;
+}
+interface MediaDevicesHookResult extends BaseHookResult, DeviceCollection {
+    devices: BaseMediaDevice[];
+}
+
+interface CameraDevice extends BaseMediaDevice<'camera'> {
+    facingMode?: 'user' | 'environment';
+}
+interface UseCameraOptions {
+    autoStart?: boolean;
+    deviceId?: string;
+    constraints?: MediaTrackConstraints;
+    facingMode?: 'user' | 'environment';
+}
+interface UseCameraResult extends BaseHookResult {
+    cameras: CameraDevice[];
+    constraints: MediaTrackConstraints;
+    currentCamera: CameraDevice | null;
+    isActive: boolean;
+    isLoading: boolean;
+    isPaused: boolean;
+    permission: HookPermissionState;
+    status: MediaStatus;
+    stream: MediaStream | null;
+    pause: () => void;
+    refreshDevices: () => Promise<void>;
+    resume: () => void;
+    start: (override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+    stop: () => void;
+    switchCamera: (deviceId: string, override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+}
+
+declare function useCamera(options?: UseCameraOptions): UseCameraResult;
+
+interface UseMediaDevicesOptions {
+    listen?: boolean;
+}
+declare function useMediaDevices(options?: UseMediaDevicesOptions): MediaDevicesHookResult;
+
+interface DeviceChangeHookResult {
+    cameras: ReturnType<typeof useMediaDevices>['cameras'];
+    changeCount: number;
+    destroy: ReturnType<typeof useMediaDevices>['destroy'];
+    devices: ReturnType<typeof useMediaDevices>['devices'];
+    error: ReturnType<typeof useMediaDevices>['error'];
+    lastChangeAt: number | null;
+    loading: boolean;
+    microphones: ReturnType<typeof useMediaDevices>['microphones'];
+    refresh: ReturnType<typeof useMediaDevices>['refresh'];
+    speakers: ReturnType<typeof useMediaDevices>['speakers'];
+    supported: boolean;
+}
+declare function useDeviceChange(): DeviceChangeHookResult;
+
+interface UseMediaRecorderResult extends BaseHookResult {
+    blob: Blob | null;
+    chunks: Blob[];
+    isPaused: boolean;
+    isRecording: boolean;
+    start: (stream: MediaStream, options?: MediaRecorderOptions) => void;
+    status: MediaStatus;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    reset: () => void;
+    download: (fileName?: string) => string | null;
+    url: string | null;
+}
+declare function useMediaRecorder(): UseMediaRecorderResult;
+
+interface MicrophoneDevice extends BaseMediaDevice<'microphone'> {
+}
+interface UseMicrophoneOptions {
+    autoStart?: boolean;
+    deviceId?: string;
+    constraints?: MediaTrackConstraints;
+    monitorVolume?: boolean;
+}
+interface UseMicrophoneResult extends BaseHookResult {
+    currentMicrophone: MicrophoneDevice | null;
+    isActive: boolean;
+    isLoading: boolean;
+    microphones: MicrophoneDevice[];
+    muted: boolean;
+    permission: HookPermissionState;
+    status: MediaStatus;
+    stream: MediaStream | null;
+    volume: number;
+    mute: () => void;
+    refreshDevices: () => Promise<void>;
+    start: (override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+    stop: () => void;
+    switchMicrophone: (deviceId: string, override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+    unmute: () => void;
+}
+
+declare function useMicrophone(options?: UseMicrophoneOptions): UseMicrophoneResult;
+
+interface UsePermissionsResult extends BaseHookResult {
+    camera: HookPermissionState;
+    microphone: HookPermissionState;
+    requestAll: () => Promise<void>;
+    requestCamera: () => Promise<void>;
+    requestMicrophone: () => Promise<void>;
+}
+declare function usePermissions(): UsePermissionsResult;
+
+interface SpeakerDevice extends BaseMediaDevice<'speaker'> {
+}
+interface UseSpeakerResult extends BaseHookResult {
+    currentSpeaker: SpeakerDevice | null;
+    isSupported: boolean;
+    permission: HookPermissionState;
+    speakers: SpeakerDevice[];
+    switchSpeaker: (deviceId: string) => Promise<boolean>;
+}
+
+type SpeakerTarget = RefObject<HTMLMediaElement | null> | HTMLMediaElement | null;
+declare function useSpeaker(target: SpeakerTarget): UseSpeakerResult;
+
+declare const version = "0.1.0";
+
+export { type BaseHookResult, type BaseMediaDevice, type CameraDevice, type DeviceCollection, type HookPermissionState, type MediaConstraints, type MediaDeviceCategory, type MediaDevicesHookResult, type MediaError, type MediaErrorCode, type MediaPermissionState, MediaProvider, type MediaStatus, type MicrophoneDevice, type SpeakerDevice, type UseCameraOptions, type UseCameraResult, type UseMicrophoneOptions, type UseMicrophoneResult, type UseSpeakerResult, useCamera, useDeviceChange, useMediaDevices, useMediaProviderConfig, useMediaRecorder, useMicrophone, usePermissions, useSpeaker, version };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+import React, { RefObject } from 'react';
+
+interface MediaProviderConfig {
+    autoRefreshOnDeviceChange?: boolean;
+    cameraConstraints?: MediaTrackConstraints;
+    microphoneConstraints?: MediaTrackConstraints;
+    monitorMicrophoneVolume?: boolean;
+}
+interface MediaProviderProps {
+    children: React.ReactNode;
+    value?: MediaProviderConfig;
+}
+declare function MediaProvider({ children, value }: MediaProviderProps): React.JSX.Element;
+declare function useMediaProviderConfig(): Required<MediaProviderConfig>;
+
+type HookPermissionState = PermissionState | 'unsupported' | 'unknown';
+type MediaPermissionState = HookPermissionState;
+type MediaDeviceCategory = 'camera' | 'microphone' | 'speaker';
+type MediaStatus = 'idle' | 'loading' | 'active' | 'paused' | 'stopped' | 'error';
+type MediaErrorCode = 'abort' | 'browser-not-supported' | 'device-in-use' | 'device-not-found' | 'invalid-state' | 'not-allowed' | 'not-readable' | 'overconstrained' | 'permission-denied' | 'permission-query-failed' | 'recorder-not-supported' | 'speaker-not-supported' | 'unknown';
+interface MediaError {
+    code: MediaErrorCode;
+    message: string;
+    cause?: unknown;
+    name?: string;
+}
+interface BaseMediaDevice<TKind extends MediaDeviceCategory = MediaDeviceCategory> {
+    deviceId: string;
+    groupId: string;
+    kind: TKind;
+    label: string;
+    raw: MediaDeviceInfo;
+}
+interface DeviceCollection {
+    cameras: BaseMediaDevice<'camera'>[];
+    microphones: BaseMediaDevice<'microphone'>[];
+    speakers: BaseMediaDevice<'speaker'>[];
+}
+interface BaseHookResult {
+    loading: boolean;
+    error: MediaError | null;
+    supported: boolean;
+    refresh: () => Promise<void>;
+    destroy: () => void;
+}
+interface MediaConstraints {
+    audio?: boolean | MediaTrackConstraints;
+    video?: boolean | MediaTrackConstraints;
+}
+interface MediaDevicesHookResult extends BaseHookResult, DeviceCollection {
+    devices: BaseMediaDevice[];
+}
+
+interface CameraDevice extends BaseMediaDevice<'camera'> {
+    facingMode?: 'user' | 'environment';
+}
+interface UseCameraOptions {
+    autoStart?: boolean;
+    deviceId?: string;
+    constraints?: MediaTrackConstraints;
+    facingMode?: 'user' | 'environment';
+}
+interface UseCameraResult extends BaseHookResult {
+    cameras: CameraDevice[];
+    constraints: MediaTrackConstraints;
+    currentCamera: CameraDevice | null;
+    isActive: boolean;
+    isLoading: boolean;
+    isPaused: boolean;
+    permission: HookPermissionState;
+    status: MediaStatus;
+    stream: MediaStream | null;
+    pause: () => void;
+    refreshDevices: () => Promise<void>;
+    resume: () => void;
+    start: (override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+    stop: () => void;
+    switchCamera: (deviceId: string, override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+}
+
+declare function useCamera(options?: UseCameraOptions): UseCameraResult;
+
+interface UseMediaDevicesOptions {
+    listen?: boolean;
+}
+declare function useMediaDevices(options?: UseMediaDevicesOptions): MediaDevicesHookResult;
+
+interface DeviceChangeHookResult {
+    cameras: ReturnType<typeof useMediaDevices>['cameras'];
+    changeCount: number;
+    destroy: ReturnType<typeof useMediaDevices>['destroy'];
+    devices: ReturnType<typeof useMediaDevices>['devices'];
+    error: ReturnType<typeof useMediaDevices>['error'];
+    lastChangeAt: number | null;
+    loading: boolean;
+    microphones: ReturnType<typeof useMediaDevices>['microphones'];
+    refresh: ReturnType<typeof useMediaDevices>['refresh'];
+    speakers: ReturnType<typeof useMediaDevices>['speakers'];
+    supported: boolean;
+}
+declare function useDeviceChange(): DeviceChangeHookResult;
+
+interface UseMediaRecorderResult extends BaseHookResult {
+    blob: Blob | null;
+    chunks: Blob[];
+    isPaused: boolean;
+    isRecording: boolean;
+    start: (stream: MediaStream, options?: MediaRecorderOptions) => void;
+    status: MediaStatus;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    reset: () => void;
+    download: (fileName?: string) => string | null;
+    url: string | null;
+}
+declare function useMediaRecorder(): UseMediaRecorderResult;
+
+interface MicrophoneDevice extends BaseMediaDevice<'microphone'> {
+}
+interface UseMicrophoneOptions {
+    autoStart?: boolean;
+    deviceId?: string;
+    constraints?: MediaTrackConstraints;
+    monitorVolume?: boolean;
+}
+interface UseMicrophoneResult extends BaseHookResult {
+    currentMicrophone: MicrophoneDevice | null;
+    isActive: boolean;
+    isLoading: boolean;
+    microphones: MicrophoneDevice[];
+    muted: boolean;
+    permission: HookPermissionState;
+    status: MediaStatus;
+    stream: MediaStream | null;
+    volume: number;
+    mute: () => void;
+    refreshDevices: () => Promise<void>;
+    start: (override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+    stop: () => void;
+    switchMicrophone: (deviceId: string, override?: MediaTrackConstraints) => Promise<MediaStream | null>;
+    unmute: () => void;
+}
+
+declare function useMicrophone(options?: UseMicrophoneOptions): UseMicrophoneResult;
+
+interface UsePermissionsResult extends BaseHookResult {
+    camera: HookPermissionState;
+    microphone: HookPermissionState;
+    requestAll: () => Promise<void>;
+    requestCamera: () => Promise<void>;
+    requestMicrophone: () => Promise<void>;
+}
+declare function usePermissions(): UsePermissionsResult;
+
+interface SpeakerDevice extends BaseMediaDevice<'speaker'> {
+}
+interface UseSpeakerResult extends BaseHookResult {
+    currentSpeaker: SpeakerDevice | null;
+    isSupported: boolean;
+    permission: HookPermissionState;
+    speakers: SpeakerDevice[];
+    switchSpeaker: (deviceId: string) => Promise<boolean>;
+}
+
+type SpeakerTarget = RefObject<HTMLMediaElement | null> | HTMLMediaElement | null;
+declare function useSpeaker(target: SpeakerTarget): UseSpeakerResult;
+
+declare const version = "0.1.0";
+
+export { type BaseHookResult, type BaseMediaDevice, type CameraDevice, type DeviceCollection, type HookPermissionState, type MediaConstraints, type MediaDeviceCategory, type MediaDevicesHookResult, type MediaError, type MediaErrorCode, type MediaPermissionState, MediaProvider, type MediaStatus, type MicrophoneDevice, type SpeakerDevice, type UseCameraOptions, type UseCameraResult, type UseMicrophoneOptions, type UseMicrophoneResult, type UseSpeakerResult, useCamera, useDeviceChange, useMediaDevices, useMediaProviderConfig, useMediaRecorder, useMicrophone, usePermissions, useSpeaker, version };