What it does

One media source, many responsive crops.

The current package uses pixel-based transforms, strict cover clamping, and optional Web Worker compute so focus math remains smooth during resize, scrolling, zooming, and playback.

Pixel-based focus

Media is positioned with translate3d(px, px, 0) scale(s) and transform-origin: 0 0 for stable, clampable cover behavior.

Video focus over time

Pass focus keyframes with timestamps. The component selects or interpolates the active focal point as video playback moves through the timeline.

Focus video tool

The editor workflow combines selector, waveform timeline, focus point list, JSON copy and paste, and multi-aspect preview panels.

Animated keyframes

Use animationMode and animationEasing to jump, animate from the previous point, or animate to the next point.

YouTube support

YouTube iframes are detected by class or host and treated as a 16:9 source before focus and crop math is applied.

Worker fallback

Focus calculations can run in a shared Web Worker with timeout and inline fallback options for responsive UI under load.

Core concepts

Focus is just normalized metadata.

Store a small object beside the media item. The renderer uses that object to keep the subject visible in every crop target.

y: 1 x: 1 y: -1 x: -1 0, 0

Coordinates live in a -1 to 1 space. x: 0 and y: 0 are center. Positive y moves toward the top, matching the package's inverted Y behavior.

Focus metadata TypeScript

type FocusAnimationMode =
  'jump' | 'from-previous' | 'to-next';

type FocusAnimationEasing =
  'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';

interface FocusPositionModel {
  x: number;
  y: number;
  w: number;
  h: number;
  s?: number;
  animationMode?: FocusAnimationMode;
  animationEasing?: FocusAnimationEasing;
}

interface VideoPosition {
  x: number;
  y: number;
  w?: number;
  h?: number;
  s?: number;
  time?: number;
  animationMode?: FocusAnimationMode;
  animationEasing?: FocusAnimationEasing;
}

Quick start

Install, import, wrap your media.

The package exports standalone Angular components, so you import only the pieces needed by the current route or component.

Install the package

Use npm or yarn in the Angular app that will render the focused media.

Import the component

Add NgxFocusPointComponent to a standalone component's imports array.

Give the host a size

Set width and height through layout CSS, aspect-ratio, or the component inputs. Focus math needs a real container box.

Installation Shell

npm i @believablecreations/ngx-focus-point

yarn add @believablecreations/ngx-focus-point

Standalone import TypeScript

import { Component } from '@angular/core';
import { NgxFocusPointComponent } from '@believablecreations/ngx-focus-point';

@Component({
  selector: 'app-hero-media',
  standalone: true,
  imports: [NgxFocusPointComponent],
  templateUrl: './hero-media.component.html',
})
export class HeroMediaComponent {
  focusX = 0.32;
  focusY = 0.18;
  scale = 1.16;
}

Image focus HTML

<ngx-focus-point
  class="hero-media"
  [focusX]="focusX"
  [focusY]="focusY"
  [scale]="scale"
  animationSpeed="220ms">
  <img src="/assets/hero.jpg" alt="Featured product">
</ngx-focus-point>

Video focus over time

Use keyframes when the subject moves.

For videos, pass an ordered list of focus points with time values in seconds. Without animation metadata, the focus holds until the next point. With animation metadata, the component interpolates position and scale across the segment.

Keyframes TypeScript

focusKeyframes = [
  {
    id: 'opening',
    x: -0.36,
    y: 0.2,
    w: 0,
    h: 0,
    s: 1.08,
    time: 0,
    animationMode: 'to-next',
    animationEasing: 'ease-in-out',
  },
  {
    id: 'center-subject',
    x: 0.04,
    y: 0.02,
    w: 0,
    h: 0,
    s: 1.22,
    time: 4.5,
    animationMode: 'from-previous',
    animationEasing: 'ease-out',
  },
  {
    id: 'end-card',
    x: 0.52,
    y: -0.18,
    w: 0,
    h: 0,
    s: 1,
    time: 9.8,
  },
];

Playback-driven video HTML

<ngx-focus-point
  class="video-crop video-crop-portrait"
  [focus]="focusKeyframes"
  [scale]="1"
  [debounceResizeUpdate]="15"
  animationSpeed="180ms">
  <video
    src="/assets/product-demo.mp4"
    controls
    muted
    playsinline
    preload="metadata"></video>
</ngx-focus-point>

The component listens to the nested video element's timeupdate event and applies the current focus point.
Bind [time] when an external timeline or scrubber should seek the nested video.
Set [syncMediaTime]="false" if another player controller owns video seeking.
Use animationMode: 'jump' for hard cuts, 'from-previous' to animate into a point, and 'to-next' to animate out of a point.

Focus video tool

Build the editor from package components.

The focus video tool is an authoring workspace: preview the crop across target ratios, click or drag the subject on the video, refine keyframes on the timeline, and copy the final JSON into your media record.

Selector

<ngx-focus-point-video-select> wraps a video or YouTube iframe and emits normalized focus data from pointer interaction.

Timeline

<ngx-focus-point-video-timeline> displays waveform, time markers, draggable focus points, playhead controls, zoom, pan, and styling settings.

Focus list

<ngx-focus-list> shows saved points, active selection, formatted time, coordinates, scale, and JSON copy or paste actions.

Tool imports TypeScript

import {
  NgxFocusListComponent,
  NgxFocusPointVideoSelectComponent,
  NgxFocusPointVideoTimelineComponent,
} from '@believablecreations/ngx-focus-point';

@Component({
  standalone: true,
  imports: [
    NgxFocusPointVideoSelectComponent,
    NgxFocusPointVideoTimelineComponent,
    NgxFocusListComponent,
  ],
})
export class VideoFocusEditorComponent {
  playbackTime = 0;
  duration = 0;
  audioBuffer: AudioBuffer | null = null;
  selectedPointId: string | null = null;
  points = [];
}

Minimal editor layout HTML

<section class="focus-editor">
  <ngx-focus-point-video-select
    [time]="playbackTime"
    [focusPoints]="points"
    [selectedFocusPoint]="selectedPoint"
    (onFocus)="upsertPoint($event)">
    <video
      src="/assets/source-video.mp4"
      controls
      playsinline
      preload="metadata"></video>
  </ngx-focus-point-video-select>

  <ngx-focus-list
    [points]="points"
    [activePointId]="selectedPointId"
    (pointSelect)="selectPoint($event)"
    (pointsPaste)="replacePoints($event)">
  </ngx-focus-list>

  <ngx-focus-point-video-timeline
    [audioBuffer]="audioBuffer"
    [currentTime]="playbackTime"
    [duration]="duration"
    [selectionPoints]="points"
    [activeSelectionPointId]="selectedPointId"
    (timeUpdate)="setPlaybackTime($event)"
    (selectionPointSelect)="selectPoint($event)"
    (selectionPointUpdate)="updatePoint($event)"
    (selectionPointDelete)="deletePoint($event)">
  </ngx-focus-point-video-timeline>
</section>

Suggested authoring flow

Load the source video, scrub to the first important scene, click the subject in the selector, repeat for later scenes, then fine tune time, x, y, scale, and animation in the timeline settings panel. Save the JSON array on the media object and render it with <ngx-focus-point [focus]="points">.

API reference

Inputs and outputs you will actually wire.

These tables summarize the current public surface exported by the package and used by the in-app demo.

ngx-focus-point

Name	Type	Purpose
`[focus]`	`FocusPositionModel[]`	Focus keyframes. Include `time` on video points when focus changes over playback.
`[focusX]`, `[focusY]`	`number`	Static focus position from -1 to 1 when not using a focus array.
`[scale]`	`number`	Zoom multiplier. `1` is natural cover size; higher values zoom in.
`[time]`	`number`	External seek time in seconds. Used by timelines and scrubbers to sync the nested video.
`[syncMediaTime]`	`boolean`	When true, the nested video is moved to `[time]` if the values drift.
`[animationSpeed]`	`string`	CSS transition duration for transform changes. Use an empty string to disable transitions.
`[debounceResizeUpdate]`	`number`	Resize debounce in milliseconds. Lower values react faster; higher values reduce recalculation frequency.
`[preservePanOnZoom]`	`boolean`	Preserves pan memory while changing zoom for the same focus point.
`[debug]`	`boolean`	Logs focus math details while developing layouts.
`[workerOptions]`	`NgxFocusPointWorkerOptions`	Configures worker timeout and inline fallback behavior.
`(error)`	`Event`	Emitted when a nested image, video, or iframe reports a load error.

Video selector

Inputs: [time], [focusPoints], [selectedFocusPoint], [scale]. Output: (onFocus).

Video timeline

Inputs: [audioBuffer], [currentTime], [duration], [selectionPoints], [playing], [zoom], [frameRate]. Outputs include (timeUpdate), point select, update, delete, close, play, and pause.

Focus list

Inputs: [points], [activePointId]. Outputs: (pointSelect) and (pointsPaste).

Recipes

Common production patterns.

These examples cover the places Focus Point usually pays for itself: hero media, responsive video crops, YouTube embeds, and strict content security policies.

Hero image

Use [focusX], [focusY], and [scale] for simple marketing and product imagery. Store those three numbers on the media record.

Multiple video ratios

Use the same [focus] array in 16:9, 1:1, 9:16, and 21:9 containers to preview or render one video source everywhere.

External scrubber

Bind [time] from a timeline component, then handle (timeUpdate) from the timeline to seek the media.

YouTube iframe

Add class youtube or use a YouTube host. The package applies 16:9 source math before crop and focus.

Strict CSP

Set [workerOptions]="{ allowInlineFallback: false }" when Blob workers are not allowed. The component falls back to local compute.

Timeline styling

The timeline settings panel can copy and paste display configuration as JSON for background, line, text, seek head, zoom, and waveform layout.

YouTube crop HTML

<ngx-focus-point [focusX]="0.18" [focusY]="0.05" [scale]="1.12">
  <iframe
    class="youtube"
    src="https://www.youtube-nocookie.com/embed/VIDEO_ID?rel=0&controls=0&disablekb=1&fs=0&iv_load_policy=3&mute=1&autoplay=1&loop=1&playlist=VIDEO_ID&playsinline=1"
    title="YouTube video player"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture">
  </iframe>
</ngx-focus-point>

Migration notes

Current docs should use the new pixel mode API.

Some older examples mention percent positioning and legacy pan options. The current package keeps the public API smaller and relies on pixel transforms internally.

Removed from older examples

Do not document or use [actions], [translateMode], [edgeMode], [panScaleMultiplier], [panClampMultiplier], [focusW], [focusH], or [resetPanOnScaleChange] for the current ngx-focus-point component.

Recommended defaults

Use <ngx-focus-point> for images, videos, and YouTube iframes.
Use [focusX] and [focusY] for static crops.
Use [focus] arrays for video focus over time.
Use the focus video tool components to create and maintain the focus JSON.

responsive image focus
responsive video crop
video focus over time
Angular media focal point
YouTube iframe focus
focus point timeline