VModal Android SDK: Semantic Video and Image Search for Kotlin Apps

What VModal Solves for Android Video Apps

Most Android video apps let users scroll through a list or filter by date and title. VModal's SDK adds a different kind of retrieval: a user can type "the cyclist crossing the bridge at sunset" and get back the moment in a video that matches, or they can supply a reference image and find visually similar frames across an entire library.

The SDK is aimed at developers who already write Kotlin with Compose or the classic View system and want to add this capability without building their own video indexing backend. According to the README, the SDK handles the gateway, request models, response parsing, signed upload streams, progress tracking, and cancellation. The application code is responsible for the screens, lifecycle, authentication and dependency injection. The SDK publishes no navigation, themes, or design system.

Architecture: Projects, Collections, and Streams

The SDK organises data around three immutable identifiers: a project, a collection, and a stream. A project corresponds to a product or application. A collection typically maps to a user. A stream is where uploads land. The README gives this example of binding a client to all three:

import com.vmodal.sdk.VModal

val content = VModal.configure(
    projectId = "food_app",
    apiKey = apiKeyLoadedByYourApp,
).scope(
    collectionName = "user_123",
    streamName = "uploads",
)

val results = content.search("the cyclist crossing the bridge at sunset")

This design keeps the SDK stateless from the application's point of view: the same `VModal.configure` call works for any user if the collection name changes. The application still owns credentials; the SDK does not impose a login screen or manage token refresh.

The README lists two search modes. Semantic video search finds moments by their described meaning. Image-semantic search finds moments that visually resemble a reference image. Both modes return typed response objects that the application maps to its own UI.

Installation and a First Search

The SDK has no entry on Maven Central or a public Gradle repository. Installation starts by cloning the repository and running the install script:

git clone https://github.com/v-modal/vmodal_sdk_android
cd vmodal_sdk_android/uinterface/sdk_android
bash install.sh install
bash install.sh check

The `install.sh check` command verifies the toolchain. The repository uses a checked-in Gradle wrapper; the README explicitly says not to replace it.

A beta API key is needed before any API call can succeed. The README points to `v-modal.com/page/contact.ts` for key requests and to the VModal Discord. The documentation entry point is `docs/android_integration_cookbook.md`, which covers the upload-to-index-to-search pipeline, Compose and classic View patterns, `content://` URI handling, WorkManager integration, and account-switch cleanup.

Upload Flow, WorkManager, and Cancellation

Uploading from the Android system photo picker requires handling a `content://` URI and streaming the data to VModal's backend. The SDK supports this with a cold upload Flow and a callback-based `UploadHandle` for compatibility with code that does not use coroutines. The README table summarises the mapping: streaming `content://` URI support is handled by the SDK, while a cancel action "that really cancels" is provided via the cold upload Flow.

For work that needs to survive beyond one screen, the README documents a `CoroutineWorker` plus cancellation-aware upload Flow pattern. This lets a background upload continue if the user navigates away. The technical introduction at `docs/introduction.md` covers runtime credentials, network behavior, and the supported toolchain in detail, but those files are not summarised in the top-level README.

The SDK's upload guide lives in `docs/sdk_doc.md`, the coroutines guide in `docs/coroutines.md`, and API key management in `docs/manage_api_key.md`.

Example Applications and Use Cases

The repository ships five example directories:

- `examples/01_starter/`: single API operations introduced one at a time. - `examples/02_search/`: a full picker-to-upload-to-index-to-search screen. - `examples/03_fullapp/`: the complete flow validated stage by stage. - `examples/04_user/`: global, per-user, multi-stream, and catalog index organisation. - `examples/05_framebase/`: a Compose application for local street-video search, named Framebase.

The README also mentions `examples/06_json_metadata/`, suggesting metadata can be attached to uploads, though the details are in the file rather than the top-level README.

The generated Kotlin API reference is hosted at `v-modal.github.io/vmodal_sdk_android/`, which is the canonical source for method signatures and parameter types.

Limitations and When to Look Elsewhere

The VModal Android SDK has several boundaries engineers should weigh before integrating it.

First, all video data goes through VModal's hosted API. There is no self-hosted option documented in the repository. Organisations with strict data residency rules or air-gapped deployments cannot use this SDK as documented.

Second, the SDK is described as a beta. The README links to a beta API key request form rather than a production key signup page. Beta software can change its API or terms without the same stability guarantees as a GA release.

Third, the repository has no GitHub releases. Versioning and upgrade procedures are not documented in the README or the files listed in the repository. Teams that need predictable dependency management through a package registry should check whether the SDK is available on Maven Central or a private Gradle host before committing to it.

A natural alternative for teams that want on-device video search is ML Kit from Google, which can run certain media analysis tasks locally without sending data to a remote API. The trade-off is scope: ML Kit does not offer open-vocabulary natural-language video search; it is a set of bounded on-device models. VModal's SDK covers a broader semantic search problem but requires API connectivity and a managed service.

Maintenance and Licence

The last push to the repository was on 2026-09-26, two days before this writing, indicating the project is under active development. The repository is not archived.

The SDK is licensed under the Apache License 2.0. This permits use in proprietary applications without requiring source disclosure, but it does require preserving the licence notice. The README notes that asset attribution is documented separately in `assets/README.md`. The Apache-2.0 licence does not restrict use by jurisdiction or industry, though VModal's own service agreement would govern use of the hosted API.

Editorial conclusion

The VModal Android SDK suits Kotlin developers who need natural-language or image-semantic search over video libraries and do not want to build upload signing, streaming, or response parsing from scratch. It is the wrong choice for teams that need a fully self-hosted backend or whose platform policy prohibits sending video data to a third-party API. Before adopting it, verify that the VModal service terms fit your data handling requirements and check the beta API key availability at v-modal.com.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. v-modal/vmodal_sdk_android on GitHub