@omelhorsite/video-sdk 0.2.0

package/dist/types/captions.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Legendas karaoke: agrupamento, estados de realce, e - o que interessa mesmo -
+ * o remapeamento das palavras do tempo do SOURCE para o tempo da timeline.
+ *
+ * A ideia que governa este ficheiro: as palavras sao guardadas em tempo do
+ * material bruto, nao do video montado. Assim, cortar, reordenar ou apertar um
+ * bloco nao invalida a transcricao - as palavras andam com os clips, e as que
+ * caem num pedaco cortado desaparecem sozinhas. Transcreve-se uma vez por
+ * fonte, e nunca mais.
+ *
+ * A matematica do agrupamento e' a mesma do motor de legendas do omelhorsite,
+ * para o resultado ser identico ao que ja foi aprovado.
+ */
+import type { Project } from "./types";
+/** Uma palavra em tempo do source a que pertence. */
+export interface CaptionWord {
+    t0: number;
+    t1: number;
+    text: string;
+}
+/** Transcricao de um asset. Vive no Project e sobrevive a` edicao. */
+export interface CaptionSource {
+    /** Asset a que estes tempos se referem. */
+    assetId: string;
+    words: CaptionWord[];
+    /** Idioma com que foi transcrito, so' para referencia. */
+    language?: string;
+}
+export interface CaptionStyle {
+    /** Tamanho da fonte como fraccao da LARGURA do projecto. */
+    fontScale: number;
+    /** Espessura do contorno como fraccao da fonte. */
+    strokeScale: number;
+    /** Centro vertical do texto (fraccao da altura). */
+    pos: number;
+    maxWords: number;
+    maxChars: number;
+    /** Corta a legenda em silencios maiores que isto. */
+    gap: number;
+    /** Tempo extra dado a` ultima palavra do grupo. */
+    tail: number;
+    color: string;
+    highlight: string;
+    stroke: string;
+    /** Largura maxima do texto como fraccao da largura do projecto. */
+    maxWidth: number;
+    fontFamily: string;
+}
+export declare const DEFAULT_CAPTION_STYLE: CaptionStyle;
+/** Corta a lista de palavras em grupos curtos (o que aparece de cada vez). */
+export declare const groupWords: (words: CaptionWord[], style: CaptionStyle) => CaptionWord[][];
+/** Um grupo no ecra com uma palavra realcada. */
+export interface CaptionState {
+    words: CaptionWord[];
+    /** Indice, dentro de `words`, da palavra realcada. */
+    active: number;
+    t0: number;
+    t1: number;
+}
+/**
+ * Um estado por palavra: o grupo inteiro fica no ecra e o realce salta de
+ * palavra em palavra. A ultima de cada grupo ganha `tail` segundos, mas nunca
+ * entra pelo grupo seguinte adentro.
+ */
+export declare const captionStates: (chunks: CaptionWord[][], tail: number) => CaptionState[];
+/**
+ * Um pedaco do source que sobreviveu a` montagem: `[in, out]` no material
+ * bruto, a comecar em `start` na timeline.
+ */
+export interface SourceSpan {
+    in: number;
+    out: number;
+    start: number;
+}
+/** Os pedacos de um asset que estao na timeline, por ordem de montagem. */
+export declare const sourceSpans: (project: Project, assetId: string) => SourceSpan[];
+export declare const remapWords: (words: CaptionWord[], spans: SourceSpan[], borda?: number) => CaptionWord[];
+/** Todas as legendas do projecto, ja em tempo de timeline e por ordem. */
+export declare const timelineWords: (project: Project) => CaptionWord[];

package/dist/types/cloud/cloud.d.ts

@@ -0,0 +1,257 @@
+/**
+ * A unica porta do oms-video para a cloud do omelhorsite.
+ *
+ * Tudo passa pelo SDK oficial (`@omelhorsite/sdk`): o device grant para
+ * entrar, o storage para os projectos, as ferramentas para transcrever e
+ * legendar. Este modulo nao sabe o que e' um ficheiro nem uma janela: recebe
+ * bytes e um `fetch`, e devolve valores.
+ *
+ * Dois clientes, de proposito (ver OAuthTokenProvider no SDK): um ANONIMO
+ * para as rotas /oauth/* (que recusam Authorization) e um credenciado para o
+ * resto. O provider de tokens renova-se sozinho e persiste no `store` que o
+ * host injecta.
+ */
+import { OAuthTokenProvider, Oms, type CaptionJob, type CaptionStyle as SdkCaptionStyle, type CaptionWord, type DeviceAuthorization, type FetchLike, type FsNode, type Progress, type TokenSet, type TokenStore } from "@omelhorsite/sdk";
+import { type CloudWord, type SubtitleCue } from "./srt";
+/**
+ * O client_id OAuth do editor de video. Nao e' um segredo (viaja em claro em
+ * todos os pedidos), mas tem de estar registado no servidor de autorizacao
+ * como cliente publico; um id desconhecido responde `invalid_client`.
+ */
+export declare const DEFAULT_CLIENT_ID = "oms-video";
+/** Os escopos mais estreitos que servem: identidade, storage e ferramentas. */
+export declare const OMS_VIDEO_SCOPES: readonly ["openid", "storage:read", "storage:write", "tools:read", "tools:write"];
+/** Pasta no storage do utilizador onde os .omsv vivem. */
+export declare const PROJECTS_FOLDER = "oms-video";
+export declare const PROJECT_EXTENSION = ".omsv";
+export interface CloudOptions {
+    /** Onde os tokens vivem. Obrigatorio: sem store nao ha' sessao que sobreviva. */
+    readonly store: TokenStore;
+    readonly clientId?: string;
+    /** Omissao: o baseUrl do SDK (https://backend.omelhorsite.pt). */
+    readonly baseUrl?: string;
+    /** Omissao: globalThis.fetch. Um host fora do sandbox do browser injecta o seu. */
+    readonly fetch?: FetchLike;
+    /** Vai no X-Oms-Client, ex. "oms-video-cli/0.1.0". */
+    readonly clientName?: string;
+    readonly scopes?: readonly string[];
+    /**
+     * Um token de sessao legado (UUID) em vez do OAuth. So' para automacao do
+     * dono; o fluxo normal e' `login()`. Com ele as rotas que recusam OAuth
+     * (upload por partes das captions) passam a estar ao alcance.
+     */
+    readonly sessionToken?: string;
+}
+/** Quem esta' autenticado, lido do id token (sub) e, se pedido, do /account. */
+export interface CloudSession {
+    /** Identificador ESTAVEL do utilizador. O handle e o email mudam; isto nao. */
+    readonly sub: string;
+    readonly scopes: readonly string[];
+    /** Expiracao do access token (epoch ms); o provider renova-o sozinho. */
+    readonly expiresAt?: number;
+    readonly handle?: string;
+    readonly email?: string;
+}
+/** O que o host mostra durante o device flow. */
+export interface LoginPrompt extends DeviceAuthorization {
+    /** O URL a abrir: o completo (codigo pre-preenchido) quando o servidor o da'. */
+    readonly url: string;
+}
+export interface LoginOptions {
+    /** Chamado UMA vez com o codigo e o URL. O host mostra-os e/ou abre o browser. */
+    readonly onPrompt: (prompt: LoginPrompt) => void | Promise<void>;
+    readonly onPoll?: (state: "pending" | "slow_down") => void;
+    readonly signal?: AbortSignal;
+    /**
+     * Substitui o intervalo que o servidor pediu. SO' para testes: em producao
+     * honra-se o `interval` do grant, e um `slow_down` sobe-o de qualquer forma.
+     */
+    readonly pollIntervalMs?: number;
+}
+/** Um .omsv na cloud. */
+export interface CloudProject {
+    readonly id: string;
+    readonly name: string;
+    readonly size: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/** Bytes com nome: o que o host tem de dar para subir alguma coisa. */
+export interface CloudFile {
+    readonly data: Blob | Uint8Array;
+    readonly name: string;
+    /** Tamanho em bytes quando se sabe: deixa o SDK escolher multipart sem ler tudo. */
+    readonly size?: number;
+    readonly contentType?: string;
+}
+export interface TransferOptions {
+    readonly onProgress?: (progress: Progress) => void;
+    readonly signal?: AbortSignal;
+}
+export interface WaitTransferOptions extends TransferOptions {
+    /** Tecto para a espera pelo job; sem ele espera-se o que for preciso. */
+    readonly waitTimeoutMs?: number;
+}
+export interface TranscribeOptions extends WaitTransferOptions {
+    /** ISO. Omissao: deteccao automatica. */
+    readonly language?: string;
+}
+export interface CloudTranscription {
+    readonly id: string;
+    readonly text: string;
+    readonly language?: string;
+    readonly cues: SubtitleCue[];
+    /**
+     * Palavras com tempos APROXIMADOS, repartidos por deixa. A ferramenta de
+     * transcricao nao devolve tempos por palavra (lacuna do SDK/backend); para
+     * tempos exactos ha' `captionsTranscribe`.
+     */
+    readonly words: CloudWord[];
+    readonly approximate: true;
+    readonly durationSeconds: number;
+}
+export interface CaptionsTranscribeOptions extends WaitTransferOptions {
+    /** Janela do video a transcrever, em segundos do inicio. Omissao: o video todo (max 15 min). */
+    readonly start?: number;
+    readonly end?: number;
+    readonly language?: string;
+}
+export interface CaptionsRenderOptions extends WaitTransferOptions {
+    /** Palavras a queimar. Omissao: as que o job ja' tem. */
+    readonly words?: CaptionWord[];
+    readonly style?: SdkCaptionStyle;
+}
+export interface CaptionsOptions extends CaptionsTranscribeOptions, CaptionsRenderOptions {
+    /** Mantem o job no servidor depois de descarregar o resultado. Omissao: apaga-o. */
+    readonly keepJob?: boolean;
+}
+export interface CaptionsResult {
+    readonly job: CaptionJob;
+    readonly words: CaptionWord[];
+    /** O mp4 legendado. */
+    readonly output: Blob;
+}
+export declare class Cloud {
+    readonly clientId: string;
+    readonly baseUrl: string;
+    readonly scopes: readonly string[];
+    /** Sem credencial: /oauth/* recusa um Authorization. */
+    readonly anon: Oms;
+    /** O provider que renova e persiste. `null` quando se usa um token de sessao. */
+    readonly tokens: OAuthTokenProvider | null;
+    /** O cliente credenciado. E' o que `client()` devolve. */
+    readonly oms: Oms;
+    /** `true` no fluxo normal (device grant). Decide o que esta' ao alcance. */
+    readonly usesOAuth: boolean;
+    private readonly store;
+    private folderId;
+    constructor(options: CloudOptions);
+    /** O `Oms` autenticado, para o que este pacote ainda nao embrulha. */
+    client(): Oms;
+    /**
+     * Device grant completo: pede o codigo, entrega-o ao host, espera a
+     * aprovacao, guarda os tokens. Resolve com a sessao.
+     */
+    login(options: LoginOptions): Promise<CloudSession>;
+    /** Revoga o grant (best-effort) e esquece os tokens. */
+    logout(): Promise<void>;
+    /** A sessao guardada, sem rede. `null` quando ninguem entrou. */
+    session(): Promise<CloudSession | null>;
+    /**
+     * Confirma a sessao no servidor. Lanca OmsAuthError se morreu.
+     *
+     * Vai ao `/oauth/userinfo`, que so' pede `openid`; o `/account` do SDK
+     * (`auth.whoami`) exige o escopo `profile`, que este cliente nao pede por
+     * omissao. So' quando `profile` foi concedido e' que o handle e o email
+     * vem preenchidos.
+     */
+    whoami(): Promise<CloudSession>;
+    /** A pasta `oms-video/` na home do utilizador; cria-a a primeira vez. */
+    projectsFolder(): Promise<FsNode>;
+    /** Os .omsv da pasta, mais recentes primeiro. */
+    listProjects(): Promise<CloudProject[]>;
+    /** Um projecto pelo id, ou pelo nome (com ou sem .omsv) dentro da pasta. */
+    findProject(idOrName: string): Promise<CloudProject | null>;
+    /**
+     * Sobe um .omsv inteiro como UM ficheiro para `oms-video/`. Acima de 32 MiB
+     * o SDK vai por multipart sozinho (passa-se `size` para nao ler tudo antes).
+     *
+     * Um projecto com o mesmo nome e' SUBSTITUIDO: o antigo e' renomeado antes,
+     * apagado (lixo) depois de o novo estar em cima, e reposto se o upload
+     * falhar. Assim nunca fica um nome ocupado por meio ficheiro.
+     */
+    uploadProject(input: CloudFile, options?: TransferOptions): Promise<CloudProject>;
+    /** Desce um .omsv inteiro para memoria, com progresso por bytes lidos. */
+    downloadProject(id: string, options?: TransferOptions): Promise<{
+        data: Uint8Array;
+        name: string;
+        project: CloudProject;
+    }>;
+    /**
+     * O URL assinado dos bytes (6 horas), para um host que prefere descarregar
+     * ele proprio, por exemplo directo para disco.
+     */
+    downloadUrl(id: string): Promise<{
+        url: string;
+        project: CloudProject;
+    }>;
+    /**
+     * Transcricao pela ferramenta `transcriptions` (o servidor delega no
+     * transcriber; nunca ha' Whisper de outro lado). Devolve o texto, as deixas
+     * do SRT e palavras com tempos aproximados - ver CloudTranscription.words.
+     */
+    transcribe(media: CloudFile, options?: TranscribeOptions): Promise<CloudTranscription>;
+    /**
+     * Passo 1 das captions: sobe o video. Com um token OAuth so' o `create`
+     * (um POST, ate' ~100 MB) esta' ao alcance; as tres rotas do upload por
+     * partes respondem 403 a OAuth, portanto acima de CAPTION_CHUNKED_THRESHOLD
+     * isto falha AQUI, com a razao, em vez de depois de subir 64 MiB.
+     */
+    captionsUpload(video: CloudFile, options?: TransferOptions): Promise<CaptionJob>;
+    /**
+     * Palavras com tempos EXACTOS (o transcriber com `words`), via um caption
+     * job: sobe o video e transcreve uma janela. Os tempos vem em segundos do
+     * inicio do video. Quota: a janela, nao o ficheiro.
+     */
+    captionsTranscribe(video: CloudFile, options?: CaptionsTranscribeOptions): Promise<{
+        job: CaptionJob;
+        words: CaptionWord[];
+    }>;
+    /** Passo 2 sobre um job ja' carregado. */
+    captionsTranscribeJob(job: CaptionJob, options?: CaptionsTranscribeOptions): Promise<{
+        job: CaptionJob;
+        words: CaptionWord[];
+    }>;
+    /** Passo 3: queima as palavras e devolve o mp4. */
+    captionsRender(jobId: string, options?: CaptionsRenderOptions): Promise<{
+        job: CaptionJob;
+        output: Blob;
+    }>;
+    /**
+     * Os tres passos: sobe, transcreve (so' se nao vierem `words`) e renderiza.
+     * Com `words` da timeline do projecto, a cloud so' faz a render: e' assim
+     * que as legendas do omelhorsite viram uma camada por cima do oms-video.
+     */
+    captions(video: CloudFile, options?: CaptionsOptions): Promise<CaptionsResult>;
+}
+/** Le a sessao de um TokenSet: o `sub` do id token e os escopos concedidos. */
+export declare const sessionFrom: (set: TokenSet) => CloudSession;
+/** Estilo das legendas do oms-video (fraccoes da LARGURA) em estilo da cloud (fraccoes da ALTURA). */
+export declare const cloudCaptionStyle: (style: {
+    fontScale?: number;
+    strokeScale?: number;
+    pos?: number;
+    maxWords?: number;
+    gap?: number;
+    color?: string;
+    highlight?: string;
+    stroke?: string;
+}, frame: {
+    width: number;
+    height: number;
+}) => SdkCaptionStyle;
+/**
+ * Uma frase em portugues para cada falha que o utilizador pode resolver.
+ * O resto sai com a mensagem original, que e' a que ajuda a depurar.
+ */
+export declare const describeCloudError: (e: unknown) => string;

package/dist/types/cloud/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./cloud";
+export * from "./srt";
+export * from "./store";
+export { DEFAULT_BASE_URL, memoryTokenStore, OmsApiError, OmsAuthError, OmsError, OmsNetworkError, OmsQuotaError, OmsTimeoutError, type CaptionJob, type CaptionStyle as CloudCaptionStyle, type FetchLike, type FsNode, type Progress, type TokenSet, type TokenStore, } from "@omelhorsite/sdk";

package/dist/types/cloud/srt.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SubRip -> palavras.
+ *
+ * A ferramenta de transcricao do omelhorsite devolve texto e legendas por
+ * SEGMENTO (SRT/VTT), nao por palavra. As legendas karaoke do oms-video
+ * precisam de um tempo por palavra, por isso cada deixa e' repartida pelas
+ * suas palavras em proporcao ao numero de caracteres. E' uma aproximacao, e
+ * vem marcada como tal: quem tem o audio pode encostar estas fronteiras aos
+ * silencios reais, e quem quer tempos exactos usa o caminho das captions
+ * (`captionsTranscribe`), que devolve tempos por palavra.
+ */
+export interface SubtitleCue {
+    t0: number;
+    t1: number;
+    text: string;
+}
+export interface CloudWord {
+    t0: number;
+    t1: number;
+    text: string;
+}
+/** Le um SRT (ou um VTT simples) com tolerancia a CRLF, indices em falta e tags. */
+export declare const parseSrt: (text: string) => SubtitleCue[];
+/**
+ * Reparte cada deixa pelas suas palavras, proporcionalmente aos caracteres
+ * (mais um por palavra, a fazer de espaco). Nunca deixa uma palavra com
+ * duracao zero e nunca ultrapassa a deixa seguinte.
+ */
+export declare const wordsFromCues: (cues: SubtitleCue[]) => CloudWord[];

package/dist/types/cloud/store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stores de tokens para os hosts.
+ *
+ * O SDK so' pede um `TokenStore` (load/save/clear de um `TokenSet`). Onde isso
+ * vive e' decisao do host: um ficheiro com permissoes apertadas, um keychain.
+ * Este modulo da' a ponte: um store de STRING (o host so' tem de
+ * guardar e devolver texto) vira um `TokenStore` tipado, com validacao do que
+ * volta - um ficheiro corrompido ou de outra versao le-se como "ninguem
+ * autenticado" e nao como uma excepcao no arranque.
+ */
+import type { TokenSet, TokenStore } from "@omelhorsite/sdk";
+/** O que o host guarda. Versionado para o dia em que o formato mudar. */
+export interface StoredCredentials {
+    version: 1;
+    /** API a que estes tokens pertencem; um store partilhado entre ambientes nao se mistura. */
+    baseUrl: string;
+    clientId: string;
+    tokens: TokenSet;
+}
+export declare const CREDENTIALS_VERSION = 1;
+/** Tres funcoes de texto que o host implementa. Todas podem ser async. */
+export interface StringStore {
+    load(): string | null | Promise<string | null>;
+    save(text: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+/** Le com tolerancia: qualquer coisa que nao seja um TokenSet valido conta como nada. */
+export declare const parseStoredCredentials: (text: string | null) => StoredCredentials | null;
+/**
+ * Um `TokenStore` por cima de um store de texto. Tokens de OUTRA API ou de
+ * outro client_id sao ignorados (e substituidos no proximo login), para um
+ * ficheiro de staging nunca autenticar contra producao.
+ *
+ * O `clear()` so' apaga o que e' desta identidade. O provider do SDK chama
+ * clear num 401 sem tokens - e se o ficheiro fosse de outro client_id, um
+ * comando lancado com o client_id errado apagava a sessao do certo.
+ */
+export declare const stringTokenStore: (inner: StringStore, identity: {
+    baseUrl: string;
+    clientId: string;
+}) => TokenStore;

package/dist/types/compile.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Compila um Project num comando ffmpeg (argv, sem shell). Corre igual no
+ * export local e no render do servidor; o preview usa a mesma matematica via
+ * placement.ts.
+ */
+import { type Project } from "./types";
+export interface CompileOptions {
+    output: string;
+    /**
+     * Clips de texto entram no ffmpeg como PNGs ja rasterizados (pelo canvas do
+     * preview, ou por PIL no servidor) - paridade perfeita e zero dependencia
+     * de drawtext/freetype no binario. Chave = id do TextClip; a imagem vem a
+     * escala de pixels do PROJECTO e e composta 1:1, centrada em (x, y).
+     */
+    textImages?: Record<string, {
+        path: string;
+        width: number;
+        height: number;
+    }>;
+    crf?: number;
+    preset?: string;
+    /**
+     * Bitrate do AAC (ex.: "256k"). O default fica em 192k para nao mexer no
+     * que ja existe, mas um master nao deve ficar ABAIXO da fonte: re-codificar
+     * um 256k para 192k perde por nada.
+     */
+    audioBitrate?: string;
+    /**
+     * Algoritmo de reamostragem do `scale`. Lanczos por omissao: a media destes
+     * videos vem a 720p de telemovel e sobe para 1080, e nessa subida o lanczos
+     * ganha visivelmente ao bicubico do ffmpeg (olhos, cabelo, cantaria).
+     */
+    scaleFlags?: string;
+    /**
+     * Encoder de video. `x264` (omissao) da o melhor bitrate/qualidade e demora;
+     * `videotoolbox` empurra o encode para o bloco de hardware do Mac e faz um
+     * master de 84s em ~12s em vez de ~150s. A qualidade por bit e pior, por
+     * isso o hardware trabalha a bitrate fixo (`bitrate`) e nao a CRF.
+     */
+    videoCodec?: "x264" | "videotoolbox";
+    /** Bitrate alvo do encoder de hardware (ex.: "14000k"). */
+    bitrate?: string;
+    /**
+     * Faixa de legendas ja rasterizada (video com alfa, largura do projecto).
+     * Entra como um input so' e um overlay so', para as legendas serem queimadas
+     * NO MESMO passe da render em vez de num segundo encode por cima. Quem a
+     * constroi e' o chamador, a partir das palavras que vivem no proprio
+     * projecto (`timelineWords`, `groupWords`, `captionStates`).
+     */
+    captionOverlay?: {
+        path: string;
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    };
+}
+export interface CompiledCommand {
+    /** Argumentos para o binario ffmpeg (sem o proprio "ffmpeg"). */
+    args: string[];
+    duration: number;
+}
+export declare const compile: (project: Project, options: CompileOptions) => CompiledCommand;

package/dist/types/fx.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Efeitos de ecra inteiro. Hoje so existe um: o "flash de onda de calor" que
+ * se usa nas transicoes destes videos verticais.
+ *
+ * A forma vem MEDIDA de uma transicao de referencia (exportada sobre fundo
+ * verde e analisada frame a frame): nao e um veu branco chapado, e um
+ * brilho amarelo palido que nasce a baixo e a esquerda, cresce ate engolir o
+ * frame em branco por um instante curto, e recolhe pelo mesmo caminho. Por
+ * baixo, a imagem sofre um empurrao de zoom e a ondulacao de calor.
+ *
+ * REGRA DE OURO: o preview e o export tem de ver a
+ * mesma coisa. Por isso a matematica vive aqui uma vez so, em duas linguagens
+ * postas lado a lado: `flashStateAt`/`flashGlowAt` para o canvas e
+ * `flashGeqExpr` para o ffmpeg. Sao a MESMA formula - se mexeres numa, mexes
+ * na outra, e test/fx.test.ts fica vermelho se se separarem.
+ */
+import type { FxClip } from "./types";
+/**
+ * A ondulacao e quantizada em bandas horizontais em vez de ser continua: o
+ * canvas desenha uma banda por `drawImage` (barato) e o ffmpeg quantiza a
+ * coordenada com o mesmo `floor`, por isso os dois lados batem certo.
+ */
+export declare const FLASH_STRIPS = 96;
+/** Ciclos que a onda percorre de cima a baixo durante a transicao. */
+export declare const FLASH_WAVE_SPEED = 1.5;
+/**
+ * Onde cai o CORTE dentro da transicao - e tambem onde dispara o obturador.
+ * Medido na referencia: som aos 6.000s numa transicao de 4.700 a 7.433.
+ * `add-flash --at` recebe o instante do corte e recua o clip por esta fraccao.
+ */
+export declare const FLASH_CUT_AT = 0.476;
+export declare const DEFAULT_FLASH: {
+    readonly intensity: 0.85;
+    readonly punch: 0.06;
+    readonly wave: 0.02;
+    readonly freq: 3.2;
+    readonly color: "#ffffff";
+    readonly warm: "#f8f399";
+    readonly focusX: 0.34;
+    readonly focusY: 0.72;
+};
+/**
+ * Duracao por omissao. A transicao de referencia foi exportada no ajuste mais
+ * lento que ha (2.73s) para se ver bem a forma; a velocidade a que isto se usa
+ * e um quarto de segundo - sete frames e meio, um golpe e nao uma passagem. A
+ * forma e a mesma, so o relogio e que muda: `duration` estica ou encolhe tudo
+ * em proporcao, e o som NAO vai atras (ver soundAssetId em types.ts).
+ */
+export declare const DEFAULT_FLASH_DURATION = 0.25;
+/**
+ * Envelope 0..1 ao longo do clip: sobe ate PEAK_AT, satura em cima (o
+ * patamar) e desce. O patamar e curto de proposito - ver HOLD_GAIN.
+ */
+export declare const flashEnvelope: (p: number) => number;
+export interface FlashState {
+    /** Progresso 0..1 dentro do clip. */
+    progress: number;
+    /** Envelope 0..1 do efeito. */
+    envelope: number;
+    /** Multiplicador de zoom sobre o centro (>= 1). */
+    zoom: number;
+    /** Amplitude da ondulacao, em fraccao da LARGURA. */
+    amp: number;
+    /** Fase da onda, em radianos. */
+    phase: number;
+}
+/** Estado do flash num instante da timeline, ou null se o clip nao esta activo. */
+export declare const flashStateAt: (t: number, clip: FxClip) => FlashState | null;
+export interface FlashGlow {
+    /** Opacidade do veu neste ponto, 0..1. */
+    alpha: number;
+    /** 0 = amarelo da orla, 1 = branco do nucleo. */
+    hot: number;
+}
+/**
+ * O brilho a uma distancia `r` do foco, medida em ALTURAS de ecra. E isto que
+ * faz o efeito parecer luz a entrar e nao um rectangulo branco: perto do foco
+ * chega a branco cedo, longe so mais tarde, e a orla fica amarela.
+ *
+ * Como o brilho so depende da distancia, o canvas nao precisa de andar pixel a
+ * pixel: desenha um gradiente radial com uns quantos stops tirados desta
+ * funcao, que e a mesma que o `geq` avalia por pixel no export.
+ */
+export declare const flashGlowAtRadius: (state: FlashState, clip: FxClip, r: number) => FlashGlow;
+/** O brilho num ponto do ecra (coordenadas 0..1). */
+export declare const flashGlowAt: (state: FlashState, clip: FxClip, xNormalized: number, yNormalized: number, aspect: number) => FlashGlow;
+/** Distancia (em alturas de ecra) a que o brilho ja nao pinta nada. */
+export declare const flashGlowReach: (state: FlashState) => number;
+/** Opacidade da sombra de um clip em primeiro plano. */
+export declare const SHADOW_OPACITY = 0.5;
+/** Quanto a sombra cai para baixo, em multiplos do raio. */
+export declare const SHADOW_DROP = 0.45;
+/**
+ * Margem que a sombra precisa a toda a volta do clip para nao ficar cortada.
+ * O canvas nao precisa (desenha para fora sozinho), o ffmpeg precisa de um
+ * `pad` explicito antes do desfoque - por isso a conta vive aqui.
+ */
+export declare const shadowMargin: (sigmaPixels: number) => number;
+/** Deslocamento horizontal da banda `band` (0..1), em fraccao da largura. */
+export declare const flashBandOffset: (state: FlashState, freq: number, band: number) => number;
+/** Banda (0..1) a que pertence uma linha, com a MESMA quantizacao do ffmpeg. */
+export declare const flashBandOf: (yNormalized: number) => number;
+/** Um flash pronto a por na timeline, com o CORTE em `cutAt`. */
+export declare const makeFlashClip: (id: string, cutAt: number, overrides?: Partial<Omit<FxClip, "id" | "kind" | "fx">>) => FxClip;
+/** O instante do corte (e do obturador) de um flash ja colocado. */
+export declare const flashCutTime: (clip: FxClip) => number;
+/** #rrggbb -> valores de plano (Y, Cb, Cr) em gama completa, BT.601. */
+export declare const hexToYuv: (hex: string) => [number, number, number];
+/**
+ * A mesma formula escrita na linguagem de expressoes do ffmpeg, para o filtro
+ * `geq`. Corre uma vez por pixel e por plano; como usa `p(x,y)`, `W` e `H` do
+ * plano CORRENTE, serve tal e qual para o luma e para os dois planos de croma
+ * (que sao metade do tamanho) sem contas extra.
+ *
+ * `warmValue`/`coldValue` sao o valor do amarelo e do branco NESTE plano.
+ *
+ * ATENCAO: o `eval` do ffmpeg so tem DEZ registos, st(0) a st(9). Um st(10)
+ * nao da erro - escreve em cima do 9 e o efeito sai calado e errado. Se
+ * precisares de mais uma variavel, inlina uma, nao inventes um registo.
+ *
+ * Registos: 1 progresso  2 envelope  3 zoom  4 "quente" no tempo  5 alpha
+ *           6 offset x   7 distancia ao foco  8 brilho  9 "quente" final
+ */
+export declare const flashGeqExpr: (clip: FxClip, warmValue: number, coldValue: number) => string;

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./placement";
+export * from "./compile";
+export * from "./packfile";
+export * from "./fx";
+export * from "./captions";
+export * from "./slice";
+export * from "./cloud/index";

package/dist/types/packfile.d.ts

@@ -0,0 +1,44 @@
+/**
+ * O formato de ficheiro .omsv: um ZIP (como um .jar) com TUDO dentro -
+ * timeline + media. Portavel, inspeccionavel por humanos (unzip) e por
+ * agentes. Media guardada SEM compressao (ja vem comprimida;
+ * gravar fica a velocidade de copia de disco).
+ *
+ *   projecto.omsv
+ *   ├── manifest.json   { format: "omsv", schema, savedAt }
+ *   ├── timeline.json   Project com asset.path RELATIVOS (assets/...)
+ *   └── assets/<id>-<nome>   a media embebida
+ *
+ * Este modulo e puro (bytes para dentro, bytes para fora): quem chama trata
+ * do filesystem.
+ */
+import type { Asset, Project } from "./types";
+export declare const OMSV_SCHEMA = 1;
+export interface OmsvManifest {
+    format: "omsv";
+    schema: number;
+    savedAt?: string;
+    appVersion?: string;
+}
+/** Um .omsv comeca por "PK"; o formato legado era JSON puro ("{"). */
+export declare const isZipData: (bytes: Uint8Array) => boolean;
+/** Nome canonico da entrada de um asset dentro do zip. */
+export declare const assetEntryName: (asset: Asset) => string;
+export interface PackInput {
+    project: Project;
+    /** Bytes de cada asset, por id. Assets ausentes ficam de fora (com aviso do chamador). */
+    assetBytes: Map<string, Uint8Array>;
+    appVersion?: string;
+    /** Instante da gravacao em ISO, se o chamador o quiser registar. */
+    nowIso?: string;
+}
+/** Serializa o projecto num .omsv. Os paths sao reescritos para relativos. */
+export declare const packProject: ({ project, assetBytes, appVersion, nowIso }: PackInput) => Uint8Array;
+export interface UnpackResult {
+    manifest: OmsvManifest;
+    /** Project tal como gravado: asset.path RELATIVOS (assets/...). */
+    project: Project;
+    /** Bytes por entrada relativa (assets/...). */
+    assetBytes: Map<string, Uint8Array>;
+}
+export declare const unpackProject: (bytes: Uint8Array) => UnpackResult;