@omelhorsite/video-sdk 0.2.0

package/dist/types/placement.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Matematica partilhada entre o preview (canvas) e o compilador (ffmpeg).
+ * A paridade preview/export nasce aqui: os dois lados chamam ESTAS funcoes,
+ * por isso nao ha duas interpretacoes da mesma timeline.
+ */
+import type { ClipTransform, Project } from "./types";
+export interface Placement {
+    /** Canto superior esquerdo e dimensoes, em pixels do projecto. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * "Fit" base: o asset ajustado por inteiro dentro da tela (contain), depois
+ * multiplicado pela escala do clip e centrado em (x, y).
+ */
+export declare const computePlacement: (assetWidth: number, assetHeight: number, project: Pick<Project, "width" | "height">, transform: ClipTransform) => Placement;
+/**
+ * Factor de fade (0..1) num instante da timeline. Fades lineares, medidos a
+ * partir das pontas do clip. PRODUTO dos dois envelopes (nao minimo): e assim
+ * que o ffmpeg compoe `fade in` + `fade out` encadeados, e o preview tem de
+ * bater com o export quando os fades se sobrepoem (docs/PLAYBACK.md 3.2).
+ */
+export declare const fadeFactor: (t: number, clip: {
+    start: number;
+    duration: number;
+    fadeIn: number;
+    fadeOut: number;
+}) => number;

package/dist/types/slice.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Recorta um Project a uma janela de tempo.
+ *
+ * Serve para iterar: mudou-se um corte aos 30s, quer-se ver os 30s aos 40s, e
+ * nao ha razao nenhuma para recodificar os outros 75 segundos. Como isto e' uma
+ * transformacao pura sobre o Project, tudo o resto - o compilador, as legendas,
+ * os efeitos - continua a funcionar sem saber que esta a ver so' um pedaco.
+ *
+ * O que sai e' um projecto normal, a comecar em zero. As legendas nao precisam
+ * de ser tocadas: vivem em tempo do SOURCE e quem as le deriva-as dos clips,
+ * que aqui ja vao aparados.
+ */
+import type { Clip, Project } from "./types";
+/** Apara um clip a` janela; `undefined` se ficar todo de fora. */
+export declare const sliceClip: (clip: Clip, from: number, to: number) => Clip | undefined;
+/**
+ * Projecto equivalente a` janela `[from, to]`, com tudo deslocado para comecar
+ * em zero.
+ */
+export declare const sliceProject: (project: Project, from: number, to: number) => Project;

package/dist/types/types.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Modelo da timeline do OMS Video. Este JSON e o contrato entre TODAS as
+ * pontas: o preview (canvas), o export local (ffmpeg) e o render no
+ * servidor. Qualquer efeito novo so entra quando existir nas tres.
+ */
+import type { CaptionSource, CaptionStyle } from "./captions";
+export type AssetKind = "video" | "image" | "audio";
+export interface Asset {
+    id: string;
+    kind: AssetKind;
+    name: string;
+    /** Caminho absoluto no disco do host. */
+    path: string;
+    /** Segundos; obrigatorio para video/audio. */
+    duration?: number;
+    width?: number;
+    height?: number;
+    /** Se o ficheiro tem stream de audio (probe); orienta o link video+audio. */
+    hasAudio?: boolean;
+    /** So apresentacao (UI): thumbnail (dataURL/URL); ignorado pelo compilador. */
+    thumb?: string;
+    /** So apresentacao (UI): imagem da waveform; ignorado pelo compilador. */
+    wave?: string;
+    /**
+     * SO PREVIEW (docs/PLAYBACK.md 3.4). O compilador de export usa SEMPRE
+     * `path` e as `width`/`height` do ORIGINAL pos-rotacao - nunca as do proxy.
+     */
+    proxyPath?: string;
+    /** So preview: PCM s16le intercalado, fonte do motor de audio. */
+    pcmPath?: string;
+    pcmFrames?: number;
+    pcmChannels?: number;
+    pcmSampleRate?: number;
+    /** So preview: filmstrip (tile horizontal) para os clips da timeline. */
+    stripPath?: string;
+    /** Versao do probe que preencheu width/height (rotacao aplicada a partir da 2). */
+    probeVersion?: number;
+}
+export interface ClipTransform {
+    /** Centro do clip em fraccoes da tela (0..1); 0.5/0.5 = centrado. */
+    x: number;
+    y: number;
+    /** Multiplicador sobre o "fit" base (1 = ajustado dentro da tela). */
+    scale: number;
+    /** 0..1 */
+    opacity: number;
+}
+interface BaseClip {
+    id: string;
+    /** Posicao na timeline, em segundos. */
+    start: number;
+    /** Duracao na timeline, em segundos. */
+    duration: number;
+    /** Segundos de fade a entrada/saida (0 = sem fade). */
+    fadeIn: number;
+    fadeOut: number;
+    /**
+     * Clips com o mesmo linkId estao associados (ex.: video + o seu audio
+     * separado): mover/aparar/dividir/apagar seguem juntos no editor ate se
+     * desassociar. Ignorado pelo compilador.
+     */
+    linkId?: string;
+}
+export interface VisualClip extends BaseClip {
+    kind: "video" | "image";
+    assetId: string;
+    /** Offset dentro do ficheiro de origem (so video). */
+    in: number;
+    transform: ClipTransform;
+    /** So video: descarta o audio proprio do clip. */
+    muted: boolean;
+    /** So video: ganho do audio proprio (0..2). */
+    volume: number;
+    /**
+     * Desfoca TUDO o que ja esta composto por baixo enquanto este clip esta no
+     * ar - o truque de "fundo desfocado, primeiro plano em grande". Sigma em
+     * fraccao da LARGURA do projecto (0.02 = 2%), para escalar sozinho quando o
+     * preview corre em baixa resolucao. 0/ausente = desligado.
+     */
+    blurBehind?: number;
+    /**
+     * Sombra por baixo do clip, para o descolar do fundo quando ele esta em
+     * primeiro plano. Raio em fraccao da LARGURA do projecto (0.015 = 1.5%),
+     * pela mesma razao que o `blurBehind`. 0/ausente = desligado.
+     */
+    shadow?: number;
+}
+export interface AudioClip extends BaseClip {
+    kind: "audio";
+    assetId: string;
+    in: number;
+    /** 0..2 */
+    volume: number;
+}
+export interface TextClip extends BaseClip {
+    kind: "text";
+    text: string;
+    /** Tamanho da fonte como fraccao da ALTURA do projecto. */
+    size: number;
+    /** #rrggbb */
+    color: string;
+    /** Centro, em fraccoes da tela. */
+    x: number;
+    y: number;
+}
+/**
+ * Efeito de ecra inteiro colocado na timeline. Vive numa track de video (para
+ * a UI o poder mostrar e arrastar) mas e SEMPRE composto no fim, por cima de
+ * tudo - video, imagens e texto - porque uma transicao apanha o frame todo.
+ * Matematica e valores por omissao em fx.ts.
+ */
+export interface FxClip extends BaseClip {
+    kind: "fx";
+    fx: "flash";
+    /** Opacidade maxima do veu de cor, 0..1. */
+    intensity: number;
+    /** Zoom extra no pico (0.07 = +7%). */
+    punch: number;
+    /** Amplitude da ondulacao, em fraccao da largura (0.022 = 2.2%). */
+    wave: number;
+    /** Ciclos da ondulacao de cima a baixo do ecra. */
+    freq: number;
+    /** Cor do nucleo do brilho, #rrggbb (branco no flash classico). */
+    color: string;
+    /** Cor da orla do brilho, #rrggbb (o ambar que da o ar de luz quente). */
+    warm: string;
+    /** Onde nasce o brilho, em fraccoes do ecra. */
+    focusX: number;
+    focusY: number;
+    /**
+     * Asset de audio disparado no CORTE (o "clique" do obturador). Toca sempre
+     * a velocidade natural: esticar a transicao NAO estica o som.
+     */
+    soundAssetId?: string;
+    /** Ganho desse som, 0..2. */
+    soundVolume?: number;
+}
+export type Clip = VisualClip | AudioClip | TextClip | FxClip;
+export type TrackKind = "video" | "audio" | "text";
+export interface Track {
+    id: string;
+    kind: TrackKind;
+    name: string;
+    clips: Clip[];
+    muted?: boolean;
+}
+export interface Project {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    fps: number;
+    /** Cor de fundo, #rrggbb. */
+    background: string;
+    /**
+     * Ordem de composicao visual: tracks "video" por ordem do array (indice 0 e
+     * o fundo), as tracks "text" por cima de todas, e os clips "fx" por cima do
+     * texto tambem (um flash apanha o frame inteiro). "audio" nao compoe imagem.
+     */
+    tracks: Track[];
+    assets: Asset[];
+    /**
+     * Transcricoes, uma por asset, em tempo do SOURCE. Ficam aqui em vez de
+     * viverem num mp4 ja legendado: assim cortar ou reordenar nao as invalida
+     * (ver captions.ts) e o texto continua editavel depois de transcrito.
+     */
+    captions?: CaptionSource[];
+    /** Estilo das legendas; omissao = DEFAULT_CAPTION_STYLE. */
+    captionStyle?: Partial<CaptionStyle>;
+}
+export declare const RESOLUTION_PRESETS: readonly [{
+    readonly id: "1080x1920";
+    readonly label: "9:16 (1080x1920)";
+    readonly width: 1080;
+    readonly height: 1920;
+}, {
+    readonly id: "1920x1080";
+    readonly label: "16:9 (1920x1080)";
+    readonly width: 1920;
+    readonly height: 1080;
+}, {
+    readonly id: "1080x1080";
+    readonly label: "1:1 (1080x1080)";
+    readonly width: 1080;
+    readonly height: 1080;
+}, {
+    readonly id: "720x1280";
+    readonly label: "9:16 (720x1280)";
+    readonly width: 720;
+    readonly height: 1280;
+}, {
+    readonly id: "1280x720";
+    readonly label: "16:9 (1280x720)";
+    readonly width: 1280;
+    readonly height: 720;
+}];
+export declare const projectDuration: (project: Project) => number;
+export declare const findAsset: (project: Project, id: string) => Asset | undefined;
+export declare const emptyProject: (width?: number, height?: number, fps?: number) => Project;
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@omelhorsite/video-sdk",
+  "version": "0.2.0",
+  "description": "The engine of the omelhorsite video editor: the .omsv project model, placement math, effects, karaoke captions, compilation to ffmpeg arguments, and the omelhorsite cloud client. Isolate-safe: no node builtins, no environment access, no stdout.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p . && tsc --noEmit -p tsconfig.test.json",
+    "check:isolate": "bun run scripts/check-isolate.ts",
+    "test": "bun run check:isolate && bun test",
+    "build": "rm -rf dist && bun build src/index.ts --target node --format esm --outdir dist --external fflate --external @omelhorsite/sdk && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@omelhorsite/sdk": "^0.5.1",
+    "fflate": "^0.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/afonsopc/omelhorsite-video-sdk.git"
+  },
+  "keywords": [
+    "video",
+    "ffmpeg",
+    "omsv",
+    "editor",
+    "captions",
+    "omelhorsite"
+  ]
+}