Can I embed MediaFind's search engine in my own app?

Yes. MediaFind exposes a typed Python SDK (mediafind.core.Engine) and a versioned HTTP API (/api/v1) over the same local engine as the desktop app, CLI, and MCP server. Both run on-device with no API keys.

Can I run it on-prem?

Yes. Run 'mediafind serve' to expose the HTTP API. It binds to localhost by default; run 'mediafind serve --host 0.0.0.0' to serve on your network, which requires a bearer token you set via MEDIAFIND_AUTH_TOKEN plus TLS (or an explicit --allow-insecure-lan to accept the risk).

MediaFind SDK & API — embed private, on-device media search

Q: Does the SDK or API send data to the cloud?

No. Indexing, search, transcript reads, and grounded Ask all run against a local index with no network calls; Ask can use a local, keyless LLM. You choose the trust boundary.

Q: Is the API stable enough to build on?

The mediafind.core SDK and the /api/v1 HTTP routes are a versioned, stability-promised contract: new optional fields may be added, but existing ones will not change or be removed without a major-version bump. The package ships a PEP 561 py.typed marker.

The same engine behind the MediaFind app — transcription, semantic search, and grounded Ask — as a typed Python SDK and a versioned HTTP API. On-device, keyless, on-prem-ready. Nothing uploaded.

One engine, three surfaces. The Python SDK, the /api/v1 HTTP API, and the MCP server all run the same local engine as the desktop app and CLI — so a library you index once is reachable from whichever surface fits your stack.

Python SDK

Install the package and import the engine. Heavy models load lazily, so import mediafind stays cheap:

pip install mediafind

from mediafind import Engine

with Engine() as mf:                      # default library (respects MEDIAFIND_DATA)
    mf.index("~/Movies")                  # transcribe + embed a file or folder
    hits = mf.search("the part about pricing", k=5)
    answer = mf.ask("what did we decide about pricing?")
    print(answer["answer"], answer["citations"])

Point at a specific library with Engine("/path/to/index.sqlite3"). Optional capabilities (CLIP visual search, a local LLM for Ask, faces) are pip extras — pip install "mediafind[visual]" and friends — and the engine degrades gracefully without them.

Method	Returns	What it does
`index(paths, **opts)`	summary dict	Transcribe + embed a file, folder, or list.
`search(query, k=5, …)`	list of hits	Semantic search over transcript segments with timestamps.
`ask(question, …)`	answer dict	Grounded Q&A with cited sources (a local LLM when installed, else extractive).
`transcript(media_path)`	dict	Transcript, summary, and segments for one indexed file.
`status()`	dict	Entitlement (Pro/free/trial), index quota, and version.

HTTP API

Prefer to call it over the wire, or embed from a non-Python stack? Start the local server and hit the versioned /api/v1 routes:

mediafind serve            # local HTTP API on http://localhost:8000

curl -X POST http://localhost:8000/api/v1/search \
  -H 'content-type: application/json' \
  -d '{"query": "the part about pricing", "k": 5}'

Endpoint	What it does
`POST /api/v1/search`	Semantic / multimodal search; ranked clips with timestamps.
`POST /api/v1/ask`	Grounded answer with cited sources + timestamps.
`GET /api/v1/transcript`	Transcript, summary, and segments for one indexed file.
`GET /api/v1/status`	Entitlement, index quota, and engine version.

/api/v1 is a frozen, versioned contract — separate from the app's internal routes — so you can build against it and not chase UI changes. Request and response shapes are typed; new optional fields may be added, but existing ones won't change without a major-version bump.

On-prem. mediafind serve binds to localhost by default. To serve it across your network, run mediafind serve --host 0.0.0.0: a non-loopback bind requires a bearer token you set via MEDIAFIND_AUTH_TOKEN, plus TLS (--ssl-keyfile/--ssl-certfile) — or an explicit --allow-insecure-lan to accept the risk.

Stays on your machine

Indexing, search, transcript reads, and Ask all run against a local index with no network calls; Ask stays keyless — a local LLM synthesizes answers when one is installed, otherwise you get a cited extractive answer. There are no API keys and no per-call cloud costs. A free tier caps indexed files; a one-time Pro purchase unlocks unlimited indexing and the Pro-only channels — no subscription, ever. Engine.status() (or GET /api/v1/status) reports the current entitlement.

Embed private, on-device media search in your own app.

Python SDK

HTTP API

Stays on your machine

Build private media search into your product.