creator-tools

Zero-dependency TypeScript utilities for video and social creators: aspect-ratio maths, tap tempo, subtitle parsing and conversion, platform frame sizes with sourced safe areas, encoding calculators, colour-palette extraction, GIF encoding, image metadata, and C2PA / AI-provenance detection.

No runtime dependencies. No network calls. Works in the browser, in Node, and in a worker. Every number it returns is one you could check by hand — and where a platform doesn't publish a number, it says so instead of inventing one.

npm install @prismposter/creator-tools

Why this exists

Most of these calculations are scattered across blog posts that quote each other, and a surprising number of the quoted figures are wrong. The one that started this library: every "TikTok safe area" pixel table on the open web is invented. TikTok publishes an overlay template, not a fixed inset — the occluded zone varies with frame dimensions, caption length, and which ad formats are running. There is no correct constant, so this library returns null for it and explains why, rather than shipping a plausible-looking number.

That's the rule the whole package follows:

• Derived numbers are derived. A 9:16 frame at 1080 wide is 1920 tall because that's what the ratio says. Every size in social-sizes is asserted against its own declared ratio by the test suite.

• Quoted numbers name their source. Every safe area links the first-party page it was read from. safeAreaSourceUrl(placement) returns that URL.

• Unknown is a value, not a blank. A platform that publishes nothing gets an explicit kind: 'unpublished' with the reason attached.

Related MCP server: capcut-mcp

Modules

aspect-ratio

Ratio arithmetic for frames about to be encoded. Handles non-integral cinema ratios (2.39:1) the same way it handles 16:9.

import {
  simplifyRatio, cropToRatio, padToRatio, alignToBlock,
} from '@prismposter/creator-tools/aspect-ratio';

simplifyRatio({ width: 1920, height: 1080 });   // { w: 16, h: 9 }

cropToRatio({ width: 1920, height: 1080 }, { w: 9, h: 16 });
// { result: { width: 608, height: 1080 },
//   removed: { top: 0, right: 656, bottom: 0, left: 656 },
//   areaKept: 0.3167 }

// Codecs want even dimensions; H.264 chroma subsampling makes an odd
// width an encoder error or a silent rescale.
alignToBlock({ width: 1081, height: 607 });      // { width: 1082, height: 608 }
alignToBlock({ width: 1080, height: 1920 }, 16); // { width: 1088, height: 1920 }

An odd crop remainder always goes to the bottom/right edge. That's arbitrary, but it's consistent — splitting it differently per call is how a batch of clips ends up a pixel out of register with each other.

social-sizes

Platform frames and safe areas, with sources.

import {
  getPlacement, frameSize, safeAreaPx, safeAreaBox, safeAreaSourceUrl,
} from '@prismposter/creator-tools/social-sizes';

const reels = getPlacement('instagram-reels')!;
frameSize(reels);           // { width: 1080, height: 1920 }
safeAreaPx(reels);          // { top: 269, bottom: 672, left: 65, right: 65 }
safeAreaBox(reels);         // { width: 950, height: 979 }
safeAreaSourceUrl(reels);   // Meta's Reels ads-guide page

const tiktok = getPlacement('tiktok-video')!;
safeAreaPx(tiktok);         // null — and that is the correct answer
tiktok.safeArea.reason;     // explains why no fixed table can be right

Meta publishes Reels and Stories as 14% top, 35% bottom, 6% each side. On a 1080×1920 frame that's 269 / 672 / 65 px. The bottom third is not a typo.

safeAreaPx returning null is meaningful — surface it to your user as "this platform publishes no fixed safe area". Don't substitute zeros, and don't borrow another platform's numbers.

subtitles

SRT, WebVTT, and ASS/SSA parsing, conversion, and timing edits. Everything routes through one neutral Cue shape rather than converting format-to-format: six formats would otherwise need thirty converters, each a place a rounding rule can quietly differ.

import { convert, parse, shift, scale, deoverlap }
  from '@prismposter/creator-tools/subtitles';

const { output, warnings } = convert(srtText, 'vtt');

// Fix subtitles authored against a different frame rate.
scale(parse(srtText).cues, 23.976 / 25);

// Nudge everything 500ms later; cues pushed before zero clamp to zero.
shift(cues, 500);

// Clip overlaps so only one cue is ever on screen.
deoverlap(cues);

Parsing is tolerant: a malformed block produces a warning and is skipped, rather than costing you the other 899 cues in the file. UTF-8 BOMs and CRLF endings are handled. VTT NOTE/STYLE blocks and inline tags (<v Roger>, <i>) are stripped; ASS override blocks ({\an8}) are too.

ASS stores centiseconds, so an ASS round-trip is lossy below 10 ms. convert() tells you so in warnings rather than letting you discover it later.

tempo

Tap tempo and the beat arithmetic an edit timeline needs.

import { estimateTempo, beatMs, noteMs, beatGrid, snapToBeat }
  from '@prismposter/creator-tools/tempo';

estimateTempo(tapTimestamps);
// { bpm: 128.02, taps: 16, spreadMs: 8.4, discarded: 1 }

beatMs(120);                              // 500
noteMs(120, 'quarter', { triplet: true }); // 333.333
beatGrid(120, 10_000);                     // [0, 500, 1000, … 10000]
snapToBeat(480, 120);                      // { timeMs: 500, deltaMs: 20 }

The estimator takes the median of a trailing window, not the mean. A tap sequence has two failure modes a mean handles badly: the first taps run late while the user finds the beat, and one missed tap creates an interval at roughly double the true period. Outliers are discarded against the median, because a mean would already have been dragged far enough to keep the bad interval inside tolerance.

spreadMs tells you how much to trust the result — under ~20 ms is a steady tapper, over ~60 ms means the estimate is soft. beatGrid computes each position from its index rather than accumulating, so a long sequence cannot drift.

encoding

File size, bitrate, timecode, and frame counts.

import { fileSizeBytes, targetBitrateKbps, bitsPerPixel, toDropFrame }
  from '@prismposter/creator-tools/encoding';

fileSizeBytes(60, 8_000);          // 60_000_000 bytes
targetBitrateKbps(120, 50_000_000); // kbps to hit a 50 MB cap
bitsPerPixel(1920, 1080, 30, 8_000); // 0.1286
toDropFrame(1_800, 29.97);           // '00:01:00;02'

Unit convention, stated once: bitrates are decimal (1 Mbps = 1,000,000 bits/s, as every encoder and platform spec means it) and file sizes are binary (1 MiB = 1,048,576 bytes, as every OS reports it). Mixing the two is why online calculators disagree by about 5%. formatBytesBinary and formatBytesDecimal are separate functions so the choice is always explicit.

Drop-frame timecode skips labels, never frames: numbers 00 and 01 are omitted at the start of each minute except every tenth. That's what keeps 29.97 timecode matching wall clock, which non-drop drifts from by ~3.6 s per hour.

palette

Median-cut colour quantisation, plus the contrast maths for putting text on what it returns.

import { extractPalette, toHex, readableTextOn } from '@prismposter/creator-tools/palette';

const swatches = extractPalette(pixels, 5);  // pixels: { r, g, b }[]
swatches.map(toHex);                          // ['#1b2430', '#3f6d8e', ...]
readableTextOn(swatches[0]);                  // { onColour: 'black' | 'white', ratio: 8.7 }

The box split is chosen at the widest gap along the dominant axis, not at the median pixel count. The textbook median split gives every box the same number of pixels, which is exactly wrong for a photograph: a large flat sky gets subdivided repeatedly while a small saturated accent -- the one colour a designer actually wants -- is averaged into its neighbour and disappears. Splitting at the gap keeps it.

When the source has fewer distinct colours than requested slots you get fewer swatches. Padding the result with near-duplicates would be a palette that lies about the image.

provenance

Is there provenance on this file, and does it say the asset was AI-generated?

import { inspectProvenance } from '@prismposter/creator-tools/provenance';

inspectProvenance(bytes);
// { hasC2paManifest: true, hasIptcSourceType: true, hasProvenance: true,
//   declaresAiGenerated: true, declaresCapture: false,
//   digitalSourceTypes: ['.../digitalsourcetype/trainedAlgorithmicMedia'],
//   assertionLabels: ['c2pa.actions.v2', 'c2pa.claim.v2'],
//   manifestOffset: 41, signatureVerified: false }

Two markings are in circulation and they are constantly confused:

1. A C2PA manifest -- a cryptographically signed Content Credential in a JUMBF box.

2. An IPTC digital source type -- a plain XMP/EXIF string with no signature at all, which anyone can write with exiftool.

A file can carry either, both, or neither. They are reported separately because they carry entirely different weight, and a great many "AI detector" write-ups treat the second as though it were the first.

It does not verify the signature. signatureVerified is always false, deliberately. Proving a manifest is valid needs the full C2PA trust list and certificate-chain validation -- that is what c2patool and c2pa-node are for, and you should use them when trust is the question. This answers the cheaper question those are overkill for, and which is often impossible in a serverless runtime that cannot ship a native binary: is a credential present, and what does it claim? That is the check you want when triaging an upload queue and routing only the interesting files on to a real verifier.

A present manifest is not a trusted manifest. Anyone can sign anything with a self-signed certificate, including a lie.

image-metadata

Read what a file says about itself -- and, more usefully, notice when it says nothing.

import { readImageMetadata, isStripped } from '@prismposter/creator-tools/image-metadata';

const meta = readImageMetadata(bytes);
meta.format;   // 'jpeg' | 'png' | 'webp' | 'gif' | ...
meta.fields;   // parsed EXIF / XMP / text fields
isStripped(meta);

Most platforms strip metadata on upload, so an image with none is the normal case rather than a suspicious one. isStripped exists so you can tell a user that instead of showing them an empty table.

gif

An animated GIF encoder: global palette, LZW, sub-blocks, the lot.

import { encodeGif, buildGlobalPalette, indexFrame } from '@prismposter/creator-tools/gif';

const palette = buildGlobalPalette(frames, 256);
const bytes = encodeGif({ width, height, palette, frames });

GIF allows 256 colours and one global palette across every frame, so the quantiser matters more than the encoder does -- which is why it shares palette's median cut rather than carrying its own.

mcp (Model Context Protocol Server)

@prismposter/creator-tools ships a zero-dependency MCP stdio server so AI assistants (Claude Desktop, Cursor, Windsurf, Cline) can query verified platform safe areas, aspect-ratio crops, bitrates, and subtitle conversions without hallucinating pixel dimensions.

Add to claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "prismposter-creator-tools": {
      "command": "npx",
      "args": ["-y", "@prismposter/creator-tools"]
    }
  }
}

Exposed MCP tools (all read-only, pure local calculations with an output schema):

• get_social_media_placement — one placement's frame size, safe-area insets in pixels, usable box and first-party documentation URL (instagram-reels, youtube-shorts, tiktok-video, etc.), plus a crop / letterbox plan for your source size

• list_social_media_placements — every placement, or one platform's, for browsing and comparison

• check_safe_area — whether a caption, logo or button box stays inside a placement's safe area, and by how many pixels it intrudes past each edge; TikTok answers unknown with the reason

• calculate_aspect_ratio — simplify any ratio, align to codec blocks, and compute centre-crop / letterbox plans for an arbitrary target ratio

• estimate_video_bitrate — encoded file size (bytes, MiB, MB), the bitrate that fits a size cap, and bits-per-pixel density

• convert_subtitles — convert between SRT, WebVTT and ASS/SSA with format detection and a timing shift

• estimate_tempo — BPM from tap timestamps, or beat and bar lengths for a known BPM

A bad call returns an MCP tool error (isError: true) whose message says how to fix it, for example the valid placement ids for an unknown one.

A hosted version runs at https://www.prismposter.com/api/mcp (Streamable HTTP, no install). It answers from prismposter.com's larger placement dataset (which also accepts the camelCase ids used on the site), takes videoKbps and targetCapMb in its bitrate tool, converts SRT and WebVTT only, and adds a get_prismposter_capabilities tool. Both are listed in the official MCP Registry as com.prismposter/creator-tools.

Design rules

1. Pure functions, no side effects, no I/O. Everything is synchronous and deterministic.

2. Invalid input returns null, it does not throw. These functions sit behind text inputs where a half-typed value is normal, not exceptional.

3. Rounding happens once, at the boundary. Sizes are whole pixels because that's what an encoder takes.

4. null means "no answer exists", and is always distinguishable from zero.

5. A wrong type still throws. Rule 2 is about values a user could type. It is not a licence to guess what a caller meant by handing a string to a function that reads bytes.

Development

npm install
npm test          # 173 tests
npm run typecheck
npm run build

Contributions welcome — see CONTRIBUTING.md. The bar for a new constant is a first-party source; the bar for a new function is a test that would fail without it.

The same maths, as browser tools

Every module here backs a free tool at prismposter.com/tools -- no account, no upload, no email. If you want the answer rather than the function, start there:

Who maintains this

PrismPoster is an AI content workspace -- image, video, remake, character and music studios that share one project, one asset library, and one timeline you can actually finish in.

This library is the boring half of that product: the arithmetic underneath the studios, extracted because it is genuinely reusable and because a subtitle parser is not a competitive advantage. provenance exists for the same reason in reverse -- building AI disclosure into a media product meant learning where the C2PA tooling is thin, and a dependency-free presence check was the piece that kept being missing.

License

MIT © PrismLabs OÜ