CameraAccess API

Quagga2 exposes a CameraAccess API for direct control of camera functionality. This API provides shortcuts for commonly used camera operations.

Access: Quagga.CameraAccess

Overview

The CameraAccess API allows you to:

All methods return Promises for async operation handling.

Methods

CameraAccess.request(videoElement, constraints)

Initializes the camera and starts playback.

Parameters:

Returns: Promise<void> - Resolves when camera is ready, rejects on error.

Example:

const video = document.querySelector('#camera-video');

// Request camera with default constraints
await Quagga.CameraAccess.request(video);

// Request specific camera
await Quagga.CameraAccess.request(video, {
  facingMode: 'environment',  // Back camera on mobile
  width: { ideal: 1280 },
  height: { ideal: 720 }
});

// Request camera by device ID
const deviceId = 'abc123...';
await Quagga.CameraAccess.request(video, { deviceId });

// Initialize camera without displaying (for probing)
await Quagga.CameraAccess.request(null);

Use cases:

CameraAccess.release()

Stops the video stream and releases all camera resources.

Returns: Promise<void> - Resolves when all tracks are stopped and resources released.

Example:

// Stop camera
await Quagga.CameraAccess.release();
console.log('Camera released');

Behavior:

  1. Pauses the video element
  2. Stops all tracks in the media stream
  3. Releases camera for use by other applications

Note: Always call release() when finished with the camera to free system resources.

CameraAccess.enumerateVideoDevices(constraints?)

Lists all available video input devices (cameras), optionally filtered by constraints.

Parameters:

Returns: Promise<MediaDeviceInfo[]> - Array of video device information.

Example:

// Get all video devices
const devices = await Quagga.CameraAccess.enumerateVideoDevices();

devices.forEach(device => {
  console.log('Device:', device.label);
  console.log('Device ID:', device.deviceId);
  console.log('Group ID:', device.groupId);
});

// Example output:
// Device: Front Camera
// Device ID: abc123...
// Device: Back Camera
// Device ID: def456...

Filtering devices with constraints:

// Get only devices that support a minimum resolution
const hdDevices = await Quagga.CameraAccess.enumerateVideoDevices({
  width: { min: 1280 },
  height: { min: 720 }
});

// Get only back-facing cameras
const backCameras = await Quagga.CameraAccess.enumerateVideoDevices({
  facingMode: 'environment'
});

// Eliminate wide-angle only cameras by specifying aspect ratio
const standardCameras = await Quagga.CameraAccess.enumerateVideoDevices({
  aspectRatio: { ideal: 1.777 }  // 16:9
});

Use cases:

Note: Device labels may be empty strings until camera permission is granted. When using constraints, the method will request temporary access to each device to test if it satisfies the constraints.

CameraAccess.getActiveStreamLabel()

Gets the label of the currently active video track.

Returns: string - Label of active video track (e.g., “Back Camera”, “USB Camera”).

Example:

const label = Quagga.CameraAccess.getActiveStreamLabel();
console.log('Using camera:', label);
// Output: "Using camera: Back Camera"

Use cases:

CameraAccess.getActiveStream()

Gets the complete MediaStream object for the currently active video.

Returns: MediaStream | null - The active MediaStream object, or null if no camera is active.

Example:

const stream = Quagga.CameraAccess.getActiveStream();

if (stream) {
  console.log('Stream ID:', stream.id);
  console.log('Stream active:', stream.active);
  console.log('Video tracks:', stream.getVideoTracks().length);
  console.log('Audio tracks:', stream.getAudioTracks().length);

  // Clone the stream
  const clonedStream = stream.clone();
}

// Pass stream to WebRTC peer connection
if (stream?.active) {
  peerConnection.addStream(stream);
}

Use cases:

Note: For accessing just the video track, use getActiveTrack() instead.

CameraAccess.getActiveTrack()

Gets the MediaStreamTrack for the currently active video.

Returns: MediaStreamTrack | null - Active video track object, or null if no camera is active.

Example:

const track = Quagga.CameraAccess.getActiveTrack();

console.log('Track state:', track.readyState);
console.log('Track settings:', track.getSettings());
console.log('Track capabilities:', track.getCapabilities());

// Get current resolution
const settings = track.getSettings();
console.log(`Resolution: ${settings.width}x${settings.height}`);

Use cases:

CameraAccess.enableTorch()

Turns on the camera torch (flash).

Returns: Promise<void> - Resolves when torch is enabled, rejects on error.

Example:

try {
  await Quagga.CameraAccess.enableTorch();
  console.log('Torch enabled');
} catch (error) {
  console.error('Failed to enable torch:', error);
}

Browser Support:

Requirements:

Note: Always wrap in try-catch as not all devices support torch.

CameraAccess.disableTorch()

Turns off the camera torch (flash).

Returns: Promise<void> - Resolves when torch is disabled, rejects on error.

Example:

try {
  await Quagga.CameraAccess.disableTorch();
  console.log('Torch disabled');
} catch (error) {
  console.error('Failed to disable torch:', error);
}

Browser Support: Same as enableTorch().

Complete Example

// Enumerate cameras and let user choose
const devices = await Quagga.CameraAccess.enumerateVideoDevices();
const backCamera = devices.find(d => d.label.includes('back'));

// Initialize camera
const video = document.querySelector('#video');
await Quagga.CameraAccess.request(video, {
  deviceId: backCamera.deviceId
});

console.log('Active camera:', Quagga.CameraAccess.getActiveStreamLabel());

// Enable torch for better scanning in dark environments
try {
  await Quagga.CameraAccess.enableTorch();
} catch (error) {
  console.log('Torch not available');
}

// ... use camera for scanning ...

// Cleanup
await Quagga.CameraAccess.disableTorch();
await Quagga.CameraAccess.release();

Torch Control in Live Scanning

For torch control during live scanning, you may want to provide a toggle button:

let torchEnabled = false;

document.querySelector('#torch-toggle').addEventListener('click', async () => {
  try {
    if (torchEnabled) {
      await Quagga.CameraAccess.disableTorch();
      torchEnabled = false;
    } else {
      await Quagga.CameraAccess.enableTorch();
      torchEnabled = true;
    }
  } catch (error) {
    console.error('Torch control failed:', error);
    alert('Torch not available on this device');
  }
});

Advanced Camera Control

For advanced camera control (zoom, focus, etc.), use the MediaStreamTrack API:

const track = Quagga.CameraAccess.getActiveTrack();
const capabilities = track.getCapabilities();

// Check if zoom is supported
if (capabilities.zoom) {
  console.log('Zoom range:', capabilities.zoom.min, '-', capabilities.zoom.max);

  // Apply zoom
  await track.applyConstraints({
    advanced: [{ zoom: 2.0 }]
  });
}

Read more: MediaStreamTrack Capabilities

Error Handling

Always handle errors when using CameraAccess methods:

try {
  await Quagga.CameraAccess.request(video);
} catch (error) {
  if (error.name === 'NotAllowedError') {
    console.error('Camera permission denied');
  } else if (error.name === 'NotFoundError') {
    console.error('No camera found');
  } else {
    console.error('Camera error:', error);
  }
}

← Back to Reference