sanity-plugin-r2-video 0.1.0

package/dist/studio/index.d.ts

@@ -0,0 +1,395 @@
+export { resolveRenditionPath } from '../storage.js';
+import { TranscodeOptions } from './transcode.worker.js';
+import { VideoCodec, AudioCodec } from 'mediabunny';
+import * as sanity from 'sanity';
+import { SanityClient } from 'sanity';
+import * as react from 'react';
+
+/** A single encoded MP4 rendition, stored as one object in R2. */
+type R2VideoRendition = {
+    width: number;
+    height: number;
+    key: string;
+    size: number;
+};
+/** A reference to another document, as Sanity stores it. */
+type R2VideoReference = {
+    _type: "reference";
+    _ref: string;
+};
+/** A reference to a Sanity image asset, as stored on a document. */
+type R2VideoPoster = {
+    _type: "image";
+    asset: R2VideoReference;
+};
+/**
+ * An `r2Video.asset` document. Metadata only — every MP4 lives in R2, and the
+ * poster lives in Sanity's own image pipeline so it inherits the CDN, the
+ * `srcset` helpers and the native preview branch.
+ */
+type R2VideoAsset = {
+    _id: string;
+    _type: "r2Video.asset";
+    /** Display name. Editable — nothing in storage depends on it. */
+    filename: string;
+    /**
+     * The media library folder this video belongs to — the same documents the
+     * image browser uses, so folders are shared rather than mirrored. Object
+     * keys keep the prefix they were uploaded under, so renaming a folder moves
+     * the video in the Studio without invalidating anything already in R2.
+     */
+    folder?: R2VideoReference;
+    poster: R2VideoPoster;
+    duration: number;
+    hasAudio: boolean;
+    renditions: R2VideoRendition[];
+    uploadedAt: string;
+};
+/** The value an `r2Video` field holds — a reference to an `r2Video.asset`. */
+type R2VideoValue = {
+    _type?: "r2Video";
+    asset?: R2VideoReference;
+};
+/** Field-level options for an `r2Video` field. */
+type R2VideoFieldOptions = {
+    /** Id of the folder new uploads from this field are filed under. */
+    folder?: string;
+};
+/**
+ * Encoding options, applied to every rendition.
+ *
+ * Every field is optional; what each falls back to is in `defaults.ts`.
+ */
+type R2VideoEncodingConfig = {
+    /**
+     * Rendition heights to produce, in any order. A source shorter than a tier
+     * skips it — nothing is ever upscaled.
+     */
+    heights?: number[];
+    /**
+     * Video codec. `avc` (h264) is the only one every browser plays from a plain
+     * `<video src>`, so change it only if you know the audience.
+     */
+    videoCodec?: VideoCodec;
+    /** Audio codec, used only when an upload opts into keeping audio. */
+    audioCodec?: AudioCodec;
+    /**
+     * Compression level passed to both encoders, from 0 (worst) to 1 (best).
+     *
+     * For codecs that support it — h264 included — this maps to a **quantizer**,
+     * not a bitrate. That means constant quality and *variable file size*: the
+     * output is as large as the footage needs to hit that quality, so detailed
+     * or grainy material produces much bigger files than flat material.
+     *
+     * ```
+     * 0.5  QP 28  good        0.75  QP 22  transparent
+     * 0.85 QP 20  transparent 1     QP 16  near-lossless, size unbounded
+     * ```
+     *
+     * QP 22 is h264's practical transparency threshold, which is why 0.75 is the
+     * default. Going to 1 can produce a file **larger than the source** when the
+     * source was exported at a normal quantizer — you are asking for a
+     * higher-fidelity encode than the original, and encoding can't add back
+     * detail that was never captured.
+     */
+    quality?: number;
+    /**
+     * Encode to a target **bitrate** instead of a quantizer.
+     *
+     * Flips the trade-off `quality` makes. The quantizer default is constant
+     * quality with variable size — grainy footage produces far bigger files than
+     * flat footage. With this on, size becomes predictable and quality varies
+     * instead: a tier lands at roughly the same weight whatever you feed it.
+     *
+     * The target is derived from frame size and `quality`, using 3 Mbps at
+     * 1920×1080 as the reference and a multiplier from the quality curve — so
+     * `0.75` is about 6.1 Mbps at 1080p, and `0.5` about 3.2 Mbps.
+     *
+     * Worth turning on when knowing what lands in the bucket matters more than
+     * every clip hitting the same visual bar.
+     */
+    preferBitrate?: boolean;
+    /**
+     * Copy the top rendition straight from the source instead of re-encoding it,
+     * when its height and codec already match. Mediabunny then copies rather
+     * than transcodes: instant, and bit-identical to the upload.
+     *
+     * Off by default because it hands size control to whoever exported the file
+     * — a 60 Mbps master would be stored at 60 Mbps. That tier is rarely the one
+     * served, since playback picks by element size, but the bytes are real.
+     */
+    nativeTopTier?: boolean;
+};
+/**
+ * Options for `r2Video`.
+ *
+ * Only `endpointUrl`, `token` and `bucketUrl` are required; what every other field
+ * falls back to is in `defaults.ts`.
+ */
+type R2VideoPluginConfig = {
+    /**
+     * Origin of the deployed Worker that owns uploads and deletes. The Worker
+     * holds the R2 binding; the Studio never touches the bucket directly.
+     */
+    endpointUrl: string;
+    /**
+     * Shared secret the Worker checks. This ships inside the Studio bundle, so
+     * it gates casual access rather than providing real authentication — pair it
+     * with the Worker's origin allowlist.
+     */
+    token: string;
+    /**
+     * Origin the renditions are served from - the bucket's public URL, or the
+     * custom domain attached to it. Source URLs are built from this plus each
+     * rendition's key, so no document stores an origin.
+     */
+    bucketUrl: string;
+    /** Sanity API version the plugin's own queries and mutations run against. */
+    apiVersion?: string;
+    /** Optional tool configuration for the Studio plugin. */
+    tool?: {
+        name?: string;
+        title?: string;
+    };
+    /** Where videos and their posters are filed in the media library. */
+    folders?: {
+        /**
+         * Document type folders are read from. Defaults to
+         * `sanity-plugin-media`'s own, so the video library and the image browser
+         * share one set. Point it elsewhere to decouple them.
+         */
+        type?: string;
+        /** Folder generated posters are filed under, created on first upload. */
+        poster?: string;
+    };
+    /** Encoding options. See `R2VideoEncodingConfig`. */
+    encoding?: R2VideoEncodingConfig;
+};
+
+type WithNested = {
+    tool: Required<NonNullable<R2VideoPluginConfig["tool"]>>;
+    folders: Required<NonNullable<R2VideoPluginConfig["folders"]>>;
+    encoding: TranscodeOptions;
+};
+type ResolvedR2VideoConfig = R2VideoPluginConfig & Required<Pick<R2VideoPluginConfig, "apiVersion">> & WithNested;
+
+/** A document still pointing at an asset, and therefore blocking its delete. */
+type ReferencingDocument = {
+    _id: string;
+    _type: string;
+    title?: string;
+};
+/** Documents that would break if the asset went away. */
+declare const findReferencingDocuments: (client: SanityClient, id: string) => Promise<ReferencingDocument[]>;
+/**
+ * Removes an asset from Sanity and R2. The order is forced twice over.
+ *
+ * The document goes before the poster, because it holds the strong reference
+ * that would otherwise 409. And Sanity goes before R2, because the two failure
+ * modes are not symmetric — an orphaned object is invisible and costs pennies,
+ * whereas a document pointing at deleted media breaks the site.
+ */
+declare const deleteVideoAsset: (client: SanityClient, config: R2VideoPluginConfig, asset: R2VideoAsset) => Promise<void>;
+
+/**
+ * A folder from the media library. These are the *same* documents the image
+ * browser uses, not a parallel set — a folder made in either place shows up in
+ * both, so there is one place folders are defined.
+ */
+type MediaFolder = {
+    _id: string;
+    name: string;
+    parentId: string | null;
+};
+declare const fetchFolders: (client: SanityClient, folderType: string) => Promise<MediaFolder[]>;
+/**
+ * Slash-joined path for a folder, walking up the parent chain. Guards against
+ * a cycle, which a hand-edited `parent` reference could otherwise create.
+ */
+declare const resolveFolderPath: (folders: MediaFolder[], id: string) => string;
+/** A folder as a picker lists it: its id and its full slash-joined path. */
+type FolderPath = {
+    id: string;
+    path: string;
+};
+/** Folder paths, sorted, for listing in a picker. */
+declare const resolveFolderPaths: (folders: MediaFolder[]) => FolderPath[];
+
+/**
+ * The Sanity plugin for R2 Video. Provides a video asset type, a reference
+ * field to it, and a tool for managing videos.
+ */
+declare const r2Video: sanity.Plugin<R2VideoPluginConfig>;
+
+/**
+ * The library document. Everything but `filename` and `folder` is written by the
+ * upload pipeline and read-only — there is nothing an editor can usefully
+ * correct by hand, and a stale `renditions` entry would point at an object that
+ * isn't in the bucket.
+ */
+declare const createVideoAssetSchema: (config: ResolvedR2VideoConfig) => {
+    title: string;
+    name: "r2Video.asset";
+    type: "document";
+    components: {
+        input: (props: sanity.ObjectInputProps) => react.JSX.Element;
+    };
+    fields: (({
+        title: string;
+        name: "filename";
+        type: "string";
+        description: string;
+        validation: (Rule: sanity.StringRule) => sanity.StringRule;
+    } & sanity.WidenValidation) | {
+        title: string;
+        name: "folder";
+        type: "reference";
+        to: {
+            type: string;
+        }[];
+        description: string;
+    } | ({
+        title: string;
+        name: "poster";
+        type: "image";
+        readOnly: true;
+        description: string;
+        validation: (Rule: sanity.ImageRule) => sanity.ImageRule;
+    } & sanity.WidenValidation) | {
+        title: string;
+        name: "duration";
+        type: "number";
+        readOnly: true;
+    } | ({
+        title: string;
+        name: "hasAudio";
+        type: "boolean";
+        readOnly: true;
+        initialValue: false;
+    } & sanity.WidenInitialValue) | {
+        title: string;
+        name: "renditions";
+        type: "array";
+        readOnly: true;
+        of: {
+            type: "object";
+            name: string;
+            fields: ({
+                name: string;
+                type: "number";
+            } | {
+                name: string;
+                type: "string";
+            })[];
+            preview: {
+                select: {
+                    width: string;
+                    height: string;
+                    size: string;
+                };
+                prepare({ width, height, size }: Record<string, any>): {
+                    title: string;
+                    subtitle: string;
+                };
+            };
+        }[];
+    } | {
+        title: string;
+        name: "uploadedAt";
+        type: "datetime";
+        readOnly: true;
+    })[];
+    preview: {
+        select: {
+            filename: string;
+            folder: string;
+            media: string;
+        };
+        prepare({ filename, folder, media }: Record<"filename" | "media" | "folder", any>): {
+            title: any;
+            subtitle: any;
+            media: any;
+        };
+    };
+};
+/**
+ * The field an `asset` object composes. Stores nothing but a reference, so the
+ * same video can be reused across documents without re-encoding it.
+ */
+declare const SCHEMA_R2_VIDEO: {
+    title: string;
+    name: "r2Video";
+    type: "object";
+    options: {
+        collapsible: false;
+    };
+    components: {
+        input: (props: sanity.ObjectInputProps<R2VideoValue>) => react.JSX.Element;
+    };
+    fields: {
+        title: string;
+        name: "asset";
+        type: "reference";
+        to: {
+            type: string;
+        }[];
+    }[];
+    preview: {
+        select: {
+            filename: string;
+            media: string;
+        };
+        prepare({ filename, media }: Record<"filename" | "media", any>): {
+            title: any;
+            media: any;
+        };
+    };
+};
+
+type UploadStage = "encoding" | "storing" | "saving";
+type UploadProgress = {
+    stage: UploadStage;
+    progress: number;
+    label: string;
+};
+type UploadRequest = {
+    client: SanityClient;
+    config: ResolvedR2VideoConfig;
+    file: File;
+    /** Media library folder id, or empty for none. */
+    folderId: string;
+    keepAudio: boolean;
+    /** Encoding settings for this upload, defaulting to the plugin's config. */
+    encoding: TranscodeOptions;
+    progressed: (progress: UploadProgress) => void;
+};
+/**
+ * Encodes a source into the full ladder, stores every rendition in R2, puts the
+ * poster through Sanity's own image pipeline, and writes the document that ties
+ * them together. Resolves with the created asset.
+ *
+ * The document is written last on purpose, so a failure can never leave a video
+ * in the library pointing at files that aren't there. Everything created before
+ * that point is rolled back if any step throws.
+ */
+declare const uploadVideo: ({ client, config, file, folderId, keepAudio, encoding, progressed, }: UploadRequest) => Promise<R2VideoAsset>;
+
+/**
+ * The rendition to play in the Studio: the second-tallest available. The top
+ * tier is several times the bytes for a player a few hundred pixels wide, and
+ * taking one step down works whatever ladder a project configures rather than
+ * pinning a tier this file has no business knowing about.
+ */
+declare const resolvePreviewRendition: (renditions: R2VideoRendition[]) => R2VideoRendition | undefined;
+type Props = {
+    renditions: R2VideoRendition[];
+    posterUrl?: string;
+};
+/**
+ * Plays the video rather than showing its first frame. Muted and looping to
+ * match how these are used on the site, but with controls — in the Studio the
+ * point is to check the footage, so scrubbing has to be possible.
+ */
+declare const VideoPreview: ({ renditions, posterUrl }: Props) => react.JSX.Element;
+
+export { type MediaFolder, type R2VideoAsset, type R2VideoEncodingConfig, type R2VideoFieldOptions, type R2VideoPluginConfig, type R2VideoPoster, type R2VideoReference, type R2VideoRendition, type R2VideoValue, type ReferencingDocument, type ResolvedR2VideoConfig, SCHEMA_R2_VIDEO, TranscodeOptions, VideoPreview, createVideoAssetSchema, deleteVideoAsset, fetchFolders, findReferencingDocuments, r2Video, resolveFolderPath, resolveFolderPaths, resolvePreviewRendition, uploadVideo };