VModal Flutter SDK: Multimodal Video Search and Upload for Android and iOS

What VModal Flutter SDK Does and Who Should Use It

Video libraries in mobile apps are typically browse-only: users scroll through thumbnails organized by date or album. The VModal SDK adds a search layer: a user can type a description ("the cyclist crossing the bridge at sunset") and the SDK returns the matching moments from uploaded video. The search uses the VModal cloud service for semantic understanding of video and image content, spoken words (AUDIO source), and text visible on screen (TEXT source).

The target audience is Flutter developers building apps that involve user-uploaded video content. The README frames the SDK's job as handling the VModal gateway, request models, responses, upload streams, progress, and cancellation, while the app retains full control over the user interface and authentication. The SDK imposes no login screen and does not persist the API key itself.

The SDK also provides typed access to collection, index, usage, and image resources. Collections are organized by projectId, collectionName, and streamName, forming a three-level namespace that lets a single API key scope multiple users' content (for example, each user's video library as a separate collectionName). The SDK enforces the naming rules (letters, digits, underscore; no __ separator; 80-character maximum) and encodes the backend key internally, so app code works with readable names without constructing backend keys manually.

Adding the SDK and Initializing a Project

The SDK is distributed via GitHub and added to a Flutter project through pubspec.yaml:

dependencies:
  vmodal_sdk_flutter:
    git:
      url: https://github.com/v-modal/vmodal_sdk_flutter.git
      ref: main

Then run:

flutter pub get

Once added, create a project instance using an API key your app provides at runtime, then create scoped handles for specific collections and streams:

import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';

final keys = MutableApiKeyProvider(runtimeApiKey);
final project = VModal.configure(
  projectId: 'food_app',
  apiKeyProvider: keys,
);
final favorites = project.scope(
  collectionName: 'user_123',
  streamName: 'favorites',
);

The projectId, collectionName, and streamName accept only letters, digits, and underscore, trimmed to 80 characters. The reserved separator __ is not allowed in project or collection names. The SDK performs this encoding internally. API keys are passed in at runtime through MutableApiKeyProvider; the SDK never persists them.

Semantic Video Search with Natural Language

Searching a collection takes a natural language query string and options:

final results = await favorites.search(
  'the cyclist crossing the bridge at sunset',
  options: const ScopedSearchOptions(
    searchSources: ['image'],
    limit: 20,
  ),
);

print('${results.cntActual} moments found');
for (final moment in results.data) {
  print(moment);
}

The searchSources field controls which aspects of the video are searched: 'image' for visual content, 'audio' for spoken words, and 'text' for on-screen text. The response is typed where the contract is stable and preserves raw JSON for new server fields.

Collection access is key-scoped. The README notes that a logical collection name copied from another account or environment can return HTTP 404 even when the search route is healthy. Before searching, verify the collection exists under the current API key using `project.listCollections(mode: 'vid_file')`.

For CCTV or security camera footage with time metadata, the search API also supports date-range filtering alongside semantic queries. Start is inclusive and end is exclusive. Datetime values must include Z or an explicit UTC offset:

final moments = await favorites.search(
  'vehicle',
  options: const ScopedSearchOptions(
    queryMetadataText: 'delivery',
    startDate: '2026-07-30T09:15:00.000+09:00',
    endDate: '2026-07-30T09:16:00.000+09:00',
    searchSources: ['image'],
  ),
);

The ScopedSearchOptions also accepts a versionLancedb parameter for applications that track a specific index version.

Streaming Upload with Progress and Cancellation

Video uploads stream from an app-accessible File without loading the entire video into memory. The upload task returns a stream for progress and a result future:

final task = favorites.upload(
  UploadSource.fromFile(File(videoPath)),
);

final progress = task.progress.listen((value) {
  print('Uploading ${value.percent}%');
});

final uploaded = await task.result;
await progress.cancel();
print('Ready: ${uploaded.fileName}');

Cancellation is exposed per-task via `task.cancel()`. The README specifies that signed single upload is the production default for every file size. Multipart upload is described as experimental and must be enabled explicitly.

For security camera or CCTV footage, the SDK accepts upload options with a filename, metadata text, metadata tags, and an offset-aware recording origin:

final task = favorites.upload(
  UploadSource.fromFile(File(cameraClipPath)),
  options: const ScopedUploadOptions(
    uploadOptions: VideoUploadOptions(
      videoFilename: 'entrance-camera.mp4',
      metadataText: 'north entrance delivery lane',
      metadataTags: ['entrance', 'delivery', 'camera-3'],
      startDatetimeUser: '2026-07-30T09:15:00+09:00',
    ),
  ),
);

The backend normalizes the datetime and returns canonical UTC epoch milliseconds in `uploaded.startTsUnixUserMs`. The caller's datetime text must include Z or an explicit UTC offset; the SDK preserves it without timezone conversion.

Example Applications in the Repository

The repository includes five example directories. example/01_full_app/ is the primary reference showing a complete Flutter application. example/02_users/ covers user-specific collection patterns. example/03_cctv/ demonstrates the CCTV footage upload and time-range search workflow. example/04_example/ and example/05_framebase/ and example/05_framebase_userlogin/ provide additional patterns. The README's agent-prompt onboarding instructs a coding agent to inspect the example/01_full_app/README.md before making changes.

The repository also provides build tooling: install.sh configures the Flutter toolchain, build.sh runs pub_get, analyze, and test, and run.sh launches the example on a device. The README includes a one-prompt agent setup that a coding agent can use to clone the repository, inspect instructions, install the toolchain, and run the tests before starting development.

A SOURCE_MANIFEST.sha256 file in the root provides a checksum of the published source, and a RELEASE_METADATA file records release information. A security_check.sh script is also present. The dartdoc_options.yaml configures the generated SDK documentation, and SDK reference documentation is hosted at v-modal.github.io/vmodal_sdk_flutter/.

Limitations and What the SDK Does Not Handle

The SDK requires a VModal API key obtained from v-modal.com/page/contact.ts. There is no offline mode and no local video indexing; all semantic search runs through the VModal cloud service. Teams that need to keep video data on-premises or in a private cloud cannot use this SDK as-is.

The SDK does not handle authentication or user identity. The README explicitly states: "The SDK never owns your login screen or persists your API key." App developers must implement their own authentication and pass the API key to MutableApiKeyProvider at runtime. If the API key is rotated, the app must update the provider.

The repository has no GitHub releases; the SDK is distributed directly from the main branch. The CHANGELOG.md in the root documents version changes, but there is no semantic versioning tag to pin to. Teams using the SDK in production should pin to a specific commit hash in pubspec.yaml rather than tracking main.

Collection naming errors are a common integration problem. The README warns that a collection name that looks correct but belongs to a different API key or environment returns HTTP 404, not an "unauthorized" or "not found" message that clearly identifies the scope problem. Defensive code should call listCollections before searching and handle the empty result case explicitly rather than assuming the collection exists.

Alternative Approaches and License

A direct alternative for in-app video search is building on a platform-native media indexing API. On iOS, the Photos framework allows querying the device photo library with metadata filters. On Android, the MediaStore API similarly provides metadata-based queries. Both are limited to metadata (date, album, filename, basic object detection where available) rather than semantic natural language queries against user-uploaded content.

For full semantic video search without using a cloud service, open-source video-to-text models can index video content locally, but require embedding model inference on-device or on a self-hosted server, with substantially more engineering effort than integrating the VModal SDK. That approach also requires the developer to build and maintain the indexing pipeline and the search query path, rather than delegating both to the SDK and the VModal service.

The repository uses the MIT license. The last push was on 2026-09-24, and the repository is not archived. For support and community discussion, the README links to a Discord server at discord.gg/XGxgBQqkaY and a Reddit community at reddit.com/r/v_modal.

Editorial conclusion

The VModal Flutter SDK suits mobile developers who need semantic video search in an Android or iOS app and want a typed Dart API rather than a raw HTTP client. The SDK handles the VModal gateway, request models, responses, upload streams, progress reporting, and cancellation; the app owns the login screen and credentials. Before shipping, verify that your target environment returns HTTP 200 for the search route and that your collection names exist under the project's API key scope, because a logical name from another account returns HTTP 404. The repository last received a push on 2026-09-24 and is not archived, indicating active development.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. v-modal/vmodal_sdk_flutter on GitHub