Flutter video search SDK: integrate scoped search in Dart
The Flutter video search SDK lets a Dart application work with indexed footage while keeping screens, login and navigation in the app. This guide uses the v1.2.2 release as its reference. It follows a single collection from configuration through a search result and frame display, then explains the lifecycle work needed when the user cancels or changes accounts.
Updated:
Install the Flutter video search SDK at a fixed release
The tagged README describes a Git dependency for the vmodal_sdk_flutter package. For a reproducible evaluation, choose the v1.2.2 tag rather than following a moving branch. Add the dependency to the existing Flutter application and resolve packages with the normal Flutter tooling. The source repository is the reference for this guide; the pub.dev package page is an additional discovery link, not evidence that every source tag is published there.
Before adapting an example, compare the selected release with the app’s Flutter and Dart constraints. Keep dependency resolution in the application’s lockfile and record the tag used for a pilot. This page shows the setup declaration; complete Dart operations remain in the pinned README so method signatures are not reconstructed from a different platform’s SDK.
dependencies:
vmodal_sdk_flutter:
git:
url: https://github.com/v-modal/vmodal_sdk_flutter.git
ref: v1.2.2Reference: v1.2.2 README.md dependency declaration; main replaced with the reviewed release tag
Configure a project and retain its collection scope
The README starts with credentials already loaded by the authenticated application. It constructs a project and then an immutable scope identifying a collection and stream. Your app still owns its login screen, account switching and credential storage. Keep the configured project with the session that created it, and pass a scope into the feature that uploads or searches its content.
Use the same scope across upload, index preparation, search and image lookup. A collection name copied from another user or environment is not a reliable shortcut. Begin by listing the collections available to the active identity. When the user changes projects, discard stale loading state and result selections so an earlier response cannot appear under the new collection label.
Search a collection and interpret its results
A useful first query describes a visible action or scene in footage you already know. The Dart README demonstrates searching with options on a retained scope and iterating the returned data. Select sources supported by that collection and release rather than copying enum names from another language. Confirm that the applicable index is ready before diagnosing an empty result as a query problem.
Present loading, empty, success and error states separately. Show source and time context next to each candidate so a person can verify the result. A semantic match is a candidate, not a statement that every requested object is present. Try an intentionally unrelated query during evaluation and inspect how the interface handles weak or irrelevant matches.
Fetch frame images after the search response
Result metadata and the image displayed in a tile arrive through different operations. Follow the tagged image-resource examples to resolve frame URLs for the returned identifiers. Preserve the originating collection and stream during that lookup. Where a bulk operation is appropriate, use the SDK’s documented contract instead of starting an unbounded request for every frame in a long list.
The README describes presigned image URLs and cache-oriented image operations. Treat a failed image fetch as a display-stage problem that can be retried without losing the search metadata. If a URL has expired, repeat the image lookup. Keep the underlying source reference and timestamp even when a thumbnail cannot be shown, so the reviewer can still understand which moment was returned.
Cancellation belongs to the Flutter screen lifecycle
The release exposes operation cancellation and streamed upload progress. A screen that subscribes to progress must release that subscription when the screen is disposed. Its cancel control should cancel the underlying operation, not merely hide a spinner. Keep that work owned by the widget or session that can decide whether results are still relevant.
Account switching needs more than key rotation. The README describes clearing upload persistence, clearing credentials and closing project resources before building state for the next identity. Plan what happens if a search finishes while the user navigates away. Check that completion against the active scope before attaching it to the visible result list or starting dependent frame downloads.
Handle errors at the stage that produced them
Distinguish credential failures, unavailable collections, unfinished indexing, transport failures and image-loading problems in the interface. Retrying the whole pipeline for every exception can upload a file again when only an image URL needs refreshing. Follow the typed failures in the pinned package and let the app provide a clear recovery action for the affected stage.
For a small acceptance test, upload one known recording, observe its indexing state, search for an expected scene and open the returned moment. Then cancel an upload, change collections during a search and retry a failed image display. These checks exercise the data and lifecycle boundaries that a happy-path demo misses. Bring the release tag and the failing stage when reporting an integration problem.