shortform-ai 0.1.8

Local-first CLI for short-form video and creator analysis

shortform-ai

Local-first CLI for short-form video and creator analysis.

Recommended persistent install for repeated Codex use:

pipx install "shortform-ai[local-transcribe]"
~/.local/bin/shortform-ai doctor

If the app is already installed with pipx:

pipx upgrade shortform-ai
pipx inject --force shortform-ai "shortform-ai[local-transcribe]"

Homebrew remains a good system install path once the formula is wired:

brew install shortform-ai

For one-off venv tests, use Python 3.12+ explicitly:

python3.12 -m venv .venv-shortform-ai
.venv-shortform-ai/bin/python -m pip install --upgrade pip
.venv-shortform-ai/bin/python -m pip install "shortform-ai[local-transcribe]" yt-dlp

Optional local transcription is available with faster-whisper:

pip install "shortform-ai[local-transcribe]"

shortform-ai analyze defaults to --transcribe auto. It uses OpenAI transcription when OPENAI_API_KEY is configured; otherwise it uses local faster-whisper when the optional extra is installed. The default local model is base, which downloads a model cache on first use. Use --transcribe-model small for better local accuracy.

Analysis requires a real transcript. If neither OpenAI transcription nor local faster-whisper is available, analyze stops with setup instructions instead of producing a transcript-free strategy pass.

For one-prompt Codex workflows, use the bootstrap command after installing the package:

shortform-ai bootstrap analyze <instagram-url-or-file> --instagram-from-chrome

It installs/updates the Codex skill, optionally imports the user's own Chrome Instagram session, runs analysis, fetches Instagram comments when possible, and writes bootstrap.json beside the analysis artifacts. The analyzer emits progress lines during long-running steps so Codex does not appear stuck. When comment fetch succeeds, bootstrap merges the audience summary back into the root report.md, audience.md, and comments.json.

For Instagram reel URLs with local Instagram auth configured, analysis also writes safe creator, aggregate metrics, and audio attribution metadata to media.json, reel.json, and report.md, including likes, comments, plays/views, creator profile fields, and named background music/original-audio title when Instagram exposes them.

Video analysis also tries to write contact_sheet.jpg and always writes report.md, a rich Markdown overview that points at the contact sheet when available. Caption-heavy reels also get onscreen_text.md; transcript.md is the audio transcript, so it may contain music lyrics instead of the visible story text.

Development usage from this monorepo:

PYTHONPATH=packages/content-ai-runtime python3 -m content_ai_runtime.cli doctor

The CLI reads a user's own local Instagram Chrome session only after an explicit shortform-ai auth instagram --from-chrome command. Session values are redacted from output and are stored in local secure storage when available.

content-ai remains available as a backwards-compatible command alias.