Package Exports
- ts-webcam
- ts-webcam/dist/ts-webcam.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ts-webcam) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
ts-webcam
A TypeScript library for managing webcam access using the MediaDevices API. This library provides a simple, type-safe interface for initializing and controlling webcam streams in web applications.
Features
- Type-safe configuration with TypeScript interfaces
- Support for multiple resolution options with automatic fallback
- Mirror and auto-rotation capabilities
- Customizable preview element integration
- Event callbacks for start and error handling
- Permission management for camera and microphone
- Advanced camera capabilities (zoom, torch, focus mode)
- Device change tracking
- Comprehensive error handling with error codes
- Detailed status tracking
Installation
npm install ts-webcam
Usage
Basic Example
import { Webcam, CameraError } from "ts-webcam";
// Create Webcam instance
const webcam = new Webcam();
// Get available video devices
const videoDevices = webcam.getVideoDevices();
const selectedDevice = videoDevices[0]; // หรือให้ผู้ใช้เลือก
// Setup configuration
webcam.setupConfiguration({
device: selectedDevice.id,
resolutions: [
{ name: "HD", width: 1280, height: 720, aspectRatio: 16 / 9 },
{ name: "VGA", width: 640, height: 480, aspectRatio: 4 / 3 },
],
allowAnyResolution: true,
mirror: true,
autoRotation: true,
previewElement: document.getElementById("preview") as HTMLVideoElement,
onStart: () => console.log("Webcam started"),
onError: (error: CameraError) => {
console.error("Error code:", error.code);
console.error("Error message:", error.message);
if (error.originalError) {
console.error("Original error:", error.originalError);
}
},
});
// Start the webcam with error handling
try {
await webcam.start();
} catch (error) {
if (error instanceof CameraError) {
switch (error.code) {
case "permission-denied":
console.log("กรุณาอนุญาตให้ใช้งานกล้อง");
break;
case "no-device":
console.log("ไม่พบอุปกรณ์กล้อง");
break;
case "camera-already-in-use":
console.log("กล้องกำลังถูกใช้งานโดยแอพอื่น");
break;
default:
console.log("เกิดข้อผิดพลาด:", error.message);
}
}
}
Error Handling
The library provides a comprehensive error handling system with specific error codes:
// Get last error
const error = webcam.getLastError();
if (error) {
console.log("Error code:", error.code);
console.log("Error message:", error.message);
if (error.originalError) {
console.log("Original error:", error.originalError);
}
}
// Clear error and reset status
webcam.clearError();
Error codes are categorized as follows:
Permission-related errors:
no-permissions-api
: Browser does not support the Permissions APIpermission-denied
: User denied camera accessmicrophone-permission-denied
: User denied microphone access
Device and configuration errors:
configuration-error
: Camera constraints cannot be satisfiedno-device
: No camera device foundno-media-devices-support
: Browser does not support media devicesinvalid-device-id
: Invalid device ID providedno-resolutions
: No resolutions specified
Camera initialization and operation errors:
camera-start-error
: Failed to start the cameracamera-initialization-error
: Failed to initialize the camerano-stream
: No video stream availablecamera-settings-error
: Failed to apply camera settingscamera-stop-error
: Failed to stop the cameracamera-already-in-use
: Camera is already in use by another application
Camera functionality errors:
zoom-not-supported
: Zoom is not supportedtorch-not-supported
: Torch is not supportedfocus-not-supported
: Focus mode is not supporteddevice-list-error
: Failed to get device list
Device Management
// Start tracking device changes
webcam.startDeviceTracking();
// Get current device lists
const allDevices = webcam.getDeviceList();
const videoDevices = webcam.getVideoDevices();
const audioInputDevices = webcam.getAudioInputDevices();
const audioOutputDevices = webcam.getAudioOutputDevices();
// Stop tracking when no longer needed
webcam.stopDeviceTracking();
Permission Management
// Check individual permissions
const cameraPermission = await webcam.checkCameraPermission();
const micPermission = await webcam.checkMicrophonePermission();
// Returns: 'granted' | 'denied' | 'prompt'
// Check both permissions at once
const permissions = await webcam.requestPermissions();
console.log("Camera permission:", permissions.camera);
console.log("Microphone permission:", permissions.microphone);
Advanced Camera Controls
// Get camera capabilities
const capabilities = webcam.getCapabilities();
// Zoom control
if (capabilities.zoom) {
try {
await webcam.setZoom(2.0); // 2x zoom
} catch (error) {
if (error instanceof CameraError && error.code === "zoom-not-supported") {
console.log("Zoom is not supported on this device");
}
}
}
// Torch control
if (capabilities.torch) {
try {
await webcam.setTorch(true);
} catch (error) {
if (error instanceof CameraError && error.code === "torch-not-supported") {
console.log("Torch is not supported on this device");
}
}
}
// Focus mode control
if (capabilities.focusMode) {
try {
await webcam.setFocusMode("continuous");
} catch (error) {
if (error instanceof CameraError && error.code === "focus-not-supported") {
console.log("Focus mode is not supported on this device");
}
}
}
Status Tracking
// Get current status
const status = webcam.getStatus(); // Returns: 'idle' | 'initializing' | 'ready' | 'error'
// Get current state
const state = webcam.getState();
console.log("Current status:", state.status);
console.log("Current capabilities:", state.capabilities);
console.log("Last error:", state.lastError);
// Get current resolution
const resolution = webcam.getCurrentResolution();
if (resolution) {
console.log(`Current resolution: ${resolution.width}x${resolution.height}`);
}
System Requirements
- Modern browser with MediaDevices API support (Chrome, Firefox, Edge, Safari)
- TypeScript (if using in a TypeScript project)
Browser Compatibility
The library is compatible with modern browsers that support the MediaDevices API:
- Chrome 47+
- Firefox 44+
- Edge 12+
- Safari 11+
- Chrome for Android 47+
- Safari on iOS 11+
Best Practices
- Always check device availability before starting the webcam
- Handle permission denials gracefully using error codes
- Provide fallback resolutions for better compatibility
- Use the
allowAnyResolution
option if exact resolution is not critical - Clean up resources by calling
stop()
when the webcam is no longer needed - Always handle errors using the provided error codes
- Check capabilities before using advanced features
License
MIT License
Support
If you encounter any issues or would like to request new features, please create an issue at our GitHub repository