v-modal/vmodal_sdk_flutter

What is VModal for Flutter?

VModal is a Flutter SDK that lets mobile apps (Android / iOS) add multimodal video search and upload capabilities. It connects your app to the VModal cloud service, which indexes video content and makes it searchable by:

Natural‑language description (e.g., “cyclist in a red jacket”)
Speech‑to‑text (audio) and on‑screen text
Visual similarity (image frames)

The SDK handles all the networking, streaming uploads, progress reporting, cancellation tokens, and typed response models, while leaving the UI completely under your control.

Core Features

Feature	What it does
Semantic video & image search	Query a video library with plain English; results include timestamps and similarity distances.
Audio & text search	Search for spoken words or on‑screen captions extracted by the backend.
Streaming uploads	Upload videos directly from a file picker or camera without loading the whole file into memory; progress is exposed as a Dart `Stream`.
Cancellation	Per‑operation cancellation tokens let you abort uploads or searches when a screen is closed.
Typed API	All request/response objects are strongly typed in Dart, making integration straightforward.
Authentication flexibility	Use a simple runtime API key or a short‑lived token obtained from your own backend for per‑user isolation.
Session & scope management	Create `VModalProject`, then `scope` it to a collection/stream (e.g., per‑user library) and perform isolated operations.
Lifecycle‑aware	Designed for mobile lifecycles – you can rotate credentials, close sessions, and clean up resources deterministically.

Getting Started (quick steps)

Add the package

dependencies:
  vmodal_sdk_flutter: ^1.2.3   # or the latest version on pub.dev

Obtain an API key – request one at https://v-modal.com/page/contact.ts.

Configure the SDK in your Dart code:

import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';

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

Upload a video (progress shown in the console):

final task = favorites.upload(
  UploadSource.fromFile(File('path/to/video.mp4')),
);
task.progress.listen((p) => print('Uploading ${p.percent}%'));
final uploaded = await task.result;
print('Uploaded as ${uploaded.fileName}');

Search the uploaded collection:

final results = await favorites.search(
  'the cyclist crossing the bridge at sunset',
  options: const ScopedSearchOptions(
    searchSources: ['image'],
    limit: 20,
  ),
);
for (final hit in results.videoHits) {
  print('${hit.fileName} @ ${hit.playbackOffsetMs}ms');
}

Close resources when the app shuts down:
```
await project.close();
```

The repository also ships a full‑featured example app (example/01_full_app) that demonstrates the whole flow—upload → index → search → image preview.

Typical Use Cases

Consumer video apps – let users search their personal video library with natural language.
Security / CCTV dashboards – upload camera clips, tag them, and later retrieve moments by object, time range, or spoken words.
E‑commerce product video catalogs – index product demos and enable shoppers to find a specific feature (“show the phone’s camera mode”).
Enterprise knowledge bases – store meeting recordings and let employees locate moments by keywords or speaker.

Documentation & Support

API reference: https://v-modal.github.io/vmodal_sdk_flutter/
Discord community: https://discord.gg/XGxgBQqkaY
Pub.dev page: https://pub.dev/packages/vmodal_sdk_flutter
Reddit community: https://www.reddit.com/r/v_modal/
Full docs (authentication, component patterns, performance, etc.) are in the docs/ folder of the repo.

License

MIT – you can freely use, modify, and distribute the SDK in commercial or open‑source Flutter apps.