ngx-media 1.0.0

package/projects/demo/tsconfig.spec.json

@@ -0,0 +1,10 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.d.ts", "src/**/*.spec.ts"]
+}

package/projects/ngx-media/README.md

@@ -0,0 +1,172 @@
+# What it is
+
+_Angular library for easier camera/media access in web apps._
+
+---
+
+# Planned features
+
+- Auto Destroy and clearance on component destroy
+- Easy to use ML features
+- Easy to use component
+
+---
+
+# Installation
+
+```bash
+npm install ngx-media
+```
+
+---
+
+# Basic usage
+
+A simple usage is like this:
+
+```ts
+@Component({
+  selector: 'app-video',
+  imports: [AsyncPipe],
+  template: ` <video #video width="300" height="400" autoplay [srcObject]="stream$ | async"></video> `,
+})
+export class Video {
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly ngxMedia = new NgxMedia(this.destroyRef);
+
+  protected readonly stream$ = this.ngxMedia.stream$;
+
+  constructor() {
+    this.ngxMedia.startStream({
+      video: { facingMode: 'user', aspectRatio: 1, width: { exact: 400 }, height: { exact: 300 }, frameRate: 30 },
+    });
+  }
+}
+```
+
+- Notice the `DestroyRef` is being passed as the only argument the constructor. It automatically ends the stream when the component destroys.
+
+Usage without passing `DestroyRef`:
+
+```ts
+@Component({
+  selector: 'app-video',
+  template: ` <video #video width="300" height="400" autoplay [srcObject]="stream()"></video> `,
+})
+export class Video implements OnDestroy {
+  private readonly ngxMedia = new NgxMedia();
+
+  protected readonly stream = this.ngxMedia.stream;
+
+  constructor() {
+    this.ngxMedia.startStream({
+      video: { facingMode: 'user', aspectRatio: 1, width: { exact: 400 }, height: { exact: 300 }, frameRate: 30 },
+    });
+  }
+
+  ngOnDestroy() {
+    this.ngxMedia.destroy();
+  }
+}
+```
+
+- You must call `destroy` at some point or the device's camera keeps streaming the video or if you just call `stopStream` some internally observables and memory allocated tasks might live and affect the memory.
+
+If you run `NgxMedia` outside of a injection context you need to pass the `Injector` to the constructor too so the signals can work fine.
+
+### **Avoid this pattern**:
+
+```ts
+@Component({
+  ...
+})
+export class MyBadComponent {
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly injector = inject(Injector);
+
+  someMethodOutsideOfInjectionContext() {
+    const ngxMedia = new NgxMedia(this.destroyRef, this.injector);
+    ngxMedia.startStream({
+      video: { facingMode: 'user', aspectRatio: 1, width: { exact: 400 }, height: { exact: 300 }, frameRate: 30 },
+    });
+  }
+}
+```
+
+---
+
+# APIs
+
+## Properties
+
+### `devices$: Observable<MediaDeviceInfo[]>`
+
+Available video-input devices. Populated automatically when the `NgxMedia` instance is created by calling `navigator.mediaDevices.enumerateDevices()`.
+
+### `constraints: Observable<MediaStreamConstraints | null>`
+
+Latest constraints used to request a stream. `null` when no stream has been requested yet.
+
+### `stream$: Observable<MediaStream | null>`
+
+Currently active `MediaStream` object. `null` when no stream is active.
+
+### `status$: Observable<CameraStatus>`
+
+Current lifecycle status of the instance.
+
+| Status       | Description                                           |
+| ------------ | ----------------------------------------------------- |
+| `IDLE`       | Instance created, no stream requested yet             |
+| `REQUESTING` | Waiting for the device to return a stream             |
+| `STREAMING`  | Stream is active                                      |
+| `STOPPED`    | Stream was stopped (at least one stream has occurred) |
+| `ERROR`      | An error occurred during one of the processes         |
+
+### `error$: Observable<MediaCaptureError | null>`
+
+Latest caught error. `null` when no error has occurred.
+
+`MediaCaptureError` codes: `permission-denied`, `device-not-found`, `https-required`, `device-busy`, `unsupported`, `unknown`.
+
+---
+
+## Methods
+
+### `getDevices$(): Observable<MediaDeviceInfo[]>`
+
+Calls `navigator.mediaDevices.enumerateDevices()` and returns an observable of video-input devices. Also updates `devices$`.
+
+Throws `MediaCaptureError` when the MediaDevices API is unavailable or HTTPS is required.
+
+### `getDevices(): void`
+
+Triggers `getDevices$()` and updates `devices$` internally. Fire-and-forget convenience wrapper.
+
+### `startStream$(constraints: MediaStreamConstraints): Observable<MediaStream>`
+
+Requests a new stream with the given constraints. If already streaming, returns the current stream. To change constraints on an active stream use `switchConstraints()` instead.
+
+### `startStream(constraints: MediaStreamConstraints, onStart?: (stream: MediaStream) => void): void`
+
+Fire-and-forget wrapper around `startStream$()`. Optional `onStart` callback is invoked with the stream once active.
+
+### `stopStream$(): Observable<MediaStream>`
+
+Stops all tracks on the current stream, sets `stream$` to `null`, and updates status to `STOPPED`.
+
+### `stopStream(onStop?: (stream: MediaStream) => void): void`
+
+Fire-and-forget wrapper around `stopStream$()`. Optional `onStop` callback is invoked with the stream before cleanup.
+
+### `switchConstraints(newConstraints: MediaStreamConstraints): void`
+
+Stops the current stream and starts a new one with the provided constraints.
+
+---
+
+# Browser notes
+
+- HTTPS required
+- Permission handling
+- Mobile Safari caveats

package/projects/ngx-media/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/ngx-media",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/projects/ngx-media/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "ngx-media",
+  "version": "1.0.0",
+  "description": "Angular library for easier camera/media access in web apps",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mybloodyusername/ngx-media.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mybloodyusername/ngx-media/issues"
+  },
+  "homepage": "https://github.com/mybloodyusername/ngx-media#readme",
+  "keywords": [
+    "angular",
+    "media",
+    "camera",
+    "video",
+    "webrtc"
+  ],
+  "peerDependencies": {
+    "@angular/common": "^22.0.0",
+    "@angular/core": "^22.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/projects/ngx-media/src/lib/models/camera.types.ts

@@ -0,0 +1,14 @@
+export enum CameraStatus {
+  IDLE = 'IDLE',
+  REQUESTING = 'REQUESTING',
+  STREAMING = 'STREAMING',
+  STOPPED = 'STOPPED',
+  ERROR = 'ERROR',
+}
+
+export interface StartCameraOptions {
+  audio?: false;
+  video?: MediaTrackConstraints | boolean;
+  deviceId?: string;
+  facingMode?: 'user' | 'environment';
+}

package/projects/ngx-media/src/lib/ngx-media.ts

@@ -0,0 +1,257 @@
+import { BehaviorSubject, catchError, defer, filter, from, map, Observable, take, tap, throwError } from 'rxjs';
+import { CameraStatus } from './models/camera.types';
+import { MediaCaptureError } from './utils/media-capture-error';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { DestroyRef, Injector, Signal } from '@angular/core';
+
+export class NgxMedia {
+  private readonly _devices$ = new BehaviorSubject<MediaDeviceInfo[]>([]);
+  private readonly _constraints$ = new BehaviorSubject<MediaStreamConstraints | null>(null);
+  private readonly _stream$ = new BehaviorSubject<MediaStream | null>(null);
+  private readonly _status$ = new BehaviorSubject<CameraStatus>(CameraStatus.IDLE);
+  private readonly _error$ = new BehaviorSubject<MediaCaptureError | null>(null);
+
+  /**
+   * Available video-input devices, populated automatically on construction
+   * via `navigator.mediaDevices.enumerateDevices()`.
+   *
+   * Re-emits whenever {@link getDevices} or {@link getDevices$} is called.
+   */
+  get devices$(): Observable<MediaDeviceInfo[]> {
+    return this._devices$.asObservable();
+  }
+
+  /**
+   * Latest constraints used to request a stream.
+   * Emits `null` until the first call to {@link startStream$} or {@link startStream}.
+   */
+  get constraints$(): Observable<MediaStreamConstraints | null> {
+    return this._constraints$.asObservable();
+  }
+
+  /**
+   * Currently active `MediaStream`. Emits `null` when no stream is active.
+   */
+  get stream$(): Observable<MediaStream | null> {
+    return this._stream$.asObservable();
+  }
+
+  /**
+   * Current lifecycle status of this instance.
+   *
+   * - `IDLE` — Created, no stream requested yet.
+   * - `REQUESTING` — Waiting for the device to return a stream.
+   * - `STREAMING` — A stream is active.
+   * - `STOPPED` — Stream was explicitly stopped (at least one stream occurred previously).
+   * - `ERROR` — An error occurred during one of the processes.
+   *
+   * @see {@link CameraStatus}
+   */
+  get status$(): Observable<CameraStatus> {
+    return this._status$.asObservable();
+  }
+
+  /**
+   * Latest caught error. Emits `null` when no error has occurred.
+   *
+   * @see {@link MediaCaptureError}
+   */
+  get error$(): Observable<MediaCaptureError | null> {
+    return this._error$.asObservable();
+  }
+
+  /**
+   * devices$ as signal.
+   * @see devices$ */
+  readonly devices: Signal<MediaDeviceInfo[]>;
+
+  /**
+   * constraints$ as signal.
+   * @see constraints$ */
+  readonly constraints: Signal<MediaStreamConstraints | null>;
+
+  /**
+   * stream$ as signal.
+   * @see stream$ */
+  readonly stream: Signal<MediaStream | null>;
+
+  /**
+   * status$ as signal.
+   * @see status$ */
+  readonly status: Signal<CameraStatus>;
+
+  /**
+   * error$ as signal.
+   * @see error$ */
+  readonly error: Signal<MediaCaptureError | null>;
+
+  constructor(
+    private readonly destroyRef?: DestroyRef,
+    private readonly injector?: Injector,
+  ) {
+    this.getDevices();
+
+    this.devices = toSignal(this._devices$, { requireSync: true, injector });
+    this.constraints = toSignal(this._constraints$, { requireSync: true, injector });
+    this.stream = toSignal(this._stream$, { requireSync: true, injector });
+    this.status = toSignal(this._status$, { requireSync: true, injector });
+    this.error = toSignal(this._error$, { requireSync: true, injector });
+
+    destroyRef?.onDestroy(() => {
+      this.destroy();
+    });
+  }
+
+  /**
+   * Enumerates available video-input devices and updates {@link devices$}.
+   *
+   * @returns Observable that emits an array of `MediaDeviceInfo` for video-input devices.
+   * @throws {MediaCaptureError} `device-not-found` — MediaDevices API is not supported.
+   * @throws {MediaCaptureError} `https-required` — Page is not in a secure context.
+   *
+   * @example
+   * ```ts
+   * ngxMedia.getDevices$().subscribe((devices) => {
+   *   console.log('Found cameras:', devices.length);
+   * });
+   * ```
+   */
+  getDevices$() {
+    return defer(() => {
+      if (!navigator.mediaDevices?.enumerateDevices) {
+        return throwError(() => new MediaCaptureError('MediaDevices API is not supported.', 'device-not-found'));
+      }
+
+      if (!window.isSecureContext) {
+        return throwError(
+          () => new MediaCaptureError('MediaDevices API requires HTTPS or localhost.', 'https-required'),
+        );
+      }
+
+      return from(navigator.mediaDevices.enumerateDevices()).pipe(
+        catchError((err) => {
+          this._status$.next(CameraStatus.ERROR);
+          return throwError(() => new MediaCaptureError(`Something went wrong: ${err?.message}`, 'unknown', err));
+        }),
+        map((mediaDeviceInfo) => mediaDeviceInfo.filter((m) => m.kind === 'videoinput')),
+        tap((v) => this._devices$.next(v)),
+      );
+    });
+  }
+
+  /**
+   * Fire-and-forget wrapper around {@link getDevices$}.
+   * Refreshes the {@link devices$} observable internally.
+   */
+  getDevices() {
+    this.getDevices$().subscribe();
+  }
+
+  /**
+   * Requests a new stream with the given constraints.
+   * If already streaming, returns the current stream — use {@link switchConstraints} to change
+   * constraints on an active stream.
+   *
+   * @param constraints - `MediaStreamConstraints` passed to `getUserMedia()`.
+   * @returns Observable that emits the active `MediaStream`.
+   * @throws {MediaCaptureError} When the device denies permission or is unavailable.
+   *
+   * @example
+   * ```ts
+   * ngxMedia.startStream$({ video: { facingMode: 'user' } }).subscribe((stream) => {
+   *   videoElement.srcObject = stream;
+   * });
+   * ```
+   */
+  startStream$(constraints: MediaStreamConstraints) {
+    this._constraints$.next(constraints);
+    if (this._status$.value === CameraStatus.STREAMING) {
+      return this._stream$.asObservable() as Observable<MediaStream>;
+    }
+    this._status$.next(CameraStatus.REQUESTING);
+    return from(navigator.mediaDevices.getUserMedia(constraints)).pipe(
+      catchError((err) => {
+        this._status$.next(CameraStatus.ERROR);
+        return throwError(() => new MediaCaptureError(`Something went wrong: ${err?.message}`, 'unknown', err));
+      }),
+      tap((stream) => {
+        this._status$.next(CameraStatus.STREAMING);
+        this._stream$.next(stream);
+      }),
+    );
+  }
+
+  /**
+   * Fire-and-forget wrapper around {@link startStream$}.
+   *
+   * @param constraints - `MediaStreamConstraints` passed to `getUserMedia()`.
+   * @param onStart - Optional callback invoked with the `MediaStream` once active.
+   *
+   * @example
+   * ```ts
+   * ngxMedia.startStream(
+   *   { video: true },
+   *   (stream) => { videoElement.srcObject = stream; },
+   * );
+   * ```
+   */
+  startStream(constraints: MediaStreamConstraints, onStart?: (stream: MediaStream) => void) {
+    this.startStream$(constraints).subscribe((stream) => onStart && onStart(stream));
+  }
+
+  /**
+   * Stops all tracks on the current stream, sets {@link stream$} to `null`,
+   * and transitions {@link status$} to `STOPPED`.
+   *
+   * @returns Observable that emits the `MediaStream` that was stopped.
+   */
+  stopStream$() {
+    return this._stream$.pipe(
+      filter((s) => s instanceof MediaStream),
+      take(1),
+      tap((stream) => {
+        stream.getTracks().forEach((track) => {
+          track.stop();
+        });
+        this._stream$.next(null);
+        this._status$.next(CameraStatus.STOPPED);
+      }),
+    );
+  }
+
+  /**
+   * Fire-and-forget wrapper around {@link stopStream$}.
+   *
+   * @param onStop - Optional callback invoked with the `MediaStream` before cleanup.
+   */
+  stopStream(onStop?: (stream: MediaStream) => void) {
+    this.stopStream$().subscribe((stream) => onStop && onStop(stream));
+  }
+
+  /**
+   * Stops the current stream and immediately starts a new one with the provided constraints.
+   * Equivalent to calling {@link stopStream} followed by {@link startStream}.
+   *
+   * @param newConstraints - `MediaStreamConstraints` for the new stream.
+   */
+  switchConstraints(newConstraints: MediaStreamConstraints) {
+    this.stopStream();
+    this.startStream(newConstraints);
+  }
+
+  destroy() {
+    const stream = this._stream$.value;
+    if (stream) {
+      stream.getTracks().forEach((track) => track.stop());
+      this._stream$.next(null);
+    }
+
+    this._status$.next(CameraStatus.STOPPED);
+
+    this._devices$.complete();
+    this._constraints$.complete();
+    this._stream$.complete();
+    this._status$.complete();
+    this._error$.complete();
+  }
+}

package/projects/ngx-media/src/lib/utils/media-capture-error.ts

@@ -0,0 +1,14 @@
+export class MediaCaptureError extends Error {
+  readonly code:
+    'permission-denied' | 'device-not-found' | 'https-required' | 'device-busy' | 'unsupported' | 'unknown';
+  readonly originalError: unknown;
+  constructor(
+    message: string,
+    code: 'permission-denied' | 'device-not-found' | 'https-required' | 'device-busy' | 'unsupported' | 'unknown',
+    originalError?: unknown,
+  ) {
+    super(message);
+    this.code = code;
+    this.originalError = originalError;
+  }
+}

package/projects/ngx-media/src/public-api.ts

@@ -0,0 +1,7 @@
+/*
+ * Public API Surface of ngx-media
+ */
+export * from './lib/ngx-media';
+
+export * from './lib/models/camera.types';
+export * from './lib/utils/media-capture-error';

package/projects/ngx-media/tsconfig.lib.json

@@ -0,0 +1,13 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.spec.ts"]
+}

package/projects/ngx-media/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

package/projects/ngx-media/tsconfig.spec.json

@@ -0,0 +1,10 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.d.ts", "src/**/*.spec.ts"]
+}

package/skills-lock.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "skills": {
+    "angular-developer": {
+      "source": "angular/skills",
+      "sourceType": "github",
+      "skillPath": "angular-developer/SKILL.md",
+      "computedHash": "400d674a14120ccaa435a263cd6551e5f5ddb84d99df8622689da46fe9e5902c"
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,40 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "paths": {
+      "ngx-media": ["./dist/ngx-media"]
+    },
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true
+  },
+  "files": [],
+  "references": [
+    {
+      "path": "./projects/ngx-media/tsconfig.lib.json"
+    },
+    {
+      "path": "./projects/ngx-media/tsconfig.spec.json"
+    },
+    {
+      "path": "./projects/demo/tsconfig.app.json"
+    },
+    {
+      "path": "./projects/demo/tsconfig.spec.json"
+    }
+  ]
+}