Skip to content

V- Modal AI: Visual Video / Image Search - Flutter Video SDK

Release Flutter SDK from c70f5dea01b2dd1729aba442c739f3ed3f331c23

vmodal-release-app08f5215a611b
diff --git a/RELEASE_METADATA b/RELEASE_METADATA
index d17cb1c..b357b2c 100644
--- a/RELEASE_METADATA
+++ b/RELEASE_METADATA
@@ -1 +1 @@
-Source-vmx-api: 3f33bf4f235c7e8ff9c244aad2de851179fa9bcc
+Source-vmx-api: c70f5dea01b2dd1729aba442c739f3ed3f331c23
diff --git a/SOURCE_MANIFEST.sha256 b/SOURCE_MANIFEST.sha256
index 33c003a..6427680 100644
--- a/SOURCE_MANIFEST.sha256
+++ b/SOURCE_MANIFEST.sha256
@@ -9,6 +9,7 @@
11b247bc6796892d67c9a821d18604db4dd6a880981b34f38460b9866e6b247f example/ios/Runner.xcworkspace/xcshareddata/WorkspaceSettings.xcsettings
13bacc486006b6b6ae11ae37b2cda0dddf588b8aa8e72c1b13e570b95f36aa59 doc/sdk_contract.md
14368b598ece0ce9b2e249148a10a92f2c80e38427c077013a1515826f4365bd test/fixtures/routes_contract.json
+186338d323ff6ab6c33939579cdb2a67a6a0222dc6966ddae8ee4641a5abc219 example/README.md
19be171481dc71a0b2803ebcd01dd8b0c5fd5778dee34c0a3cabc948c225f24e example/ios/Runner/Assets.xcassets/AppIcon.appiconset/[email protected]
19be171481dc71a0b2803ebcd01dd8b0c5fd5778dee34c0a3cabc948c225f24e example/ios/Runner/Assets.xcassets/AppIcon.appiconset/[email protected]
1a8d11d01d1cc92c650c9c9ed35299240052d4683a15a719a2315ef44185e074 example/ios/Runner/Runner-Bridging-Header.h
@@ -18,8 +19,10 @@
28960838bdddfa72b39ce7e86a23d547d5e5ec755498249af966d3733605dacc build.sh
28c321f8798c0e803246c737e0b634c5f3ade930239bb6e5429098bb2b096d86 doc/manage_api_key.md
28f1ad1be044eb3fbee9a9435c4905a8296ba1ded9a9508fda5436f0de7b93bf lib/src/routes.dart
+2a8d9374364cb4bae0583bbc8f27a178258f5c6298722353716829e30ec11e19 RELEASE_METADATA
2ad9b4183bce96eacd91c5514de9231b1f0a4f269392726e174507cfa507981a lib/src/http.dart
2b969fbd1d82d89a5dc7822032ce9fe0df4bda625da969bc8e93c57e43fcf2c2 pubspec.yaml
+2eaee2d6e00f6085ad65d7ff63a20963e78b635cb3d41eb15be4f37f55430295 example/asset/video_10frames.mp4
30b0832ed8b92dfbd6ae2abfa939ccf26333d37600056b1572bd4a397a18a74b example/android/app/src/debug/AndroidManifest.xml
30b0832ed8b92dfbd6ae2abfa939ccf26333d37600056b1572bd4a397a18a74b example/android/app/src/profile/AndroidManifest.xml
3156038fbb15ba2048a87f190b14744c13e4b858f1247b373f419090432ac7a2 lib/src/utils.dart
@@ -35,10 +38,8 @@
451c6d9ba0a2b3ff43092ea349c60fa79a91f1158b915eb29dbdd357cb95d7b8 example/ios/Runner/AppDelegate.swift
4630bdec004652eae39bd30f1e864a5b6e5f27a7d98f866bdea192b4d65b4046 lib/src/adaptive_upload.dart
46c3c9702ff7c5584e11c954d943cfb6e07fb26e3fbd072ddbc0f388aa352de1 example/ios/Runner.xcworkspace/contents.xcworkspacedata
-471beea99cb1189fe081eb0fbe0365025b15ab9b7d9909461ac2c6bcae195d25 example/lib/main.dart
47ce679eef585b28fe5e10a92a642eef4946c5d33d56411202734139b1db8e7b example/android/app/src/main/kotlin/com/vmodal/sdk/vmodal_example/MainActivity.kt
4d470bf22d5c17d84edc5f82516d1ba8a1c09559cd761cefb792f86d9f52b540 example/android/app/src/main/res/mipmap-xxhdpi/ic_launcher.png
-5b386cfbac75cc03ab5bac6f075fd33bbac03d880911cd43384ae0c12c8fc2df example/pubspec.yaml
5c90a4437c33000865ee889e1e2afb875d3e1abc83e5d3150e867efe1240232c doc/sdk_doc.md
5d6f8ff6f9e38deb47587b6df7bc765732d3dd4efb3677bb02e47c032ddb7c13 doc/release.md
5d7e5bdf01b93802bc973345b3a78c038907147625035952a08a115a563b7f81 example/ios/Runner/Assets.xcassets/AppIcon.appiconset/[email protected]
@@ -66,8 +67,8 @@
93ae7d494fad0fb30cbf3ae746a39c4bc7a0f8bbf87fbb587a3f3c01f3c5ce20 example/ios/Runner/Assets.xcassets/LaunchImage.imageset/[email protected]
94433756fe10005ddd6fc55cc5c0b1e9f3c10b66a08ceac795ece6713d34e28a example/android/app/src/main/res/drawable/launch_background.xml
970aad998c7e3d34430ff59c72aa224e60155f85038efa7ffc6fdf73b531437a test/regression_manifest_test.dart
+9e974714fa0e673a84f9bf6ead3a96bfd53b99063ee4f8cb5bbc6451238998b5 example/lib/main.dart
9fbce429f56243561dd437a527136c9f9ed77165e3b271b923faf236cfcd0484 example/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme
-9fcf83984baf7b89f8c243c5dd68096362469f808165573769ee332f7ebaa46a RELEASE_METADATA
a3134f6fc8387589e96a345ea35d4c68240c7c1893ef5cd5926707e4168e5309 lib/src/transport.dart
a80b38547f5d9ca1874f60e71c648e3fc12ab5f7cb88d1bead6d5b863d3c0245 readme_assets/dev_homepage.jpg
a82d7765b37116ee4821d2cd1d65942febf8032353757ffb0826eabde785b4a6 example/ios/Flutter/Debug.xcconfig
@@ -88,6 +89,7 @@ ba941377f1ee717091dd30522609d028f32cd60df575564c75ab0228c2543d35 test/config_ro
be59599b9ba77d031e9b4bad7f8d5c59efd2687888c5b73be4fbea115902106b test/adaptive_upload_test.dart
c13557f89597f0be73f48dc8463aa7513e9e814c0e6a0ab871e441834687abb1 test/upload_test.dart
c56419d129059b64551e06f074e88ef62676f25938dc2a1fe28a6ab3f2ba8547 readme_assets/logo_vmodal_owl.jpeg
+c5798c4db716557be44b294ba1d56160c8b36e11511325cf089af0d21df8a96f example/pubspec.yaml
c5ce516b547327aab5b6fa27a523d4c76e66294ada3248b293c54b9595cd3a87 example/.metadata
c6e6d3b215ae744a9c391f4c4d44157eff5e739d6ad6c39f9bfa5df66dddd267 example/ios/Runner/Assets.xcassets/AppIcon.appiconset/[email protected]
c7c0c0189145e4e32a401c61c9bdc615754b0264e7afae24e834bb81049eaf81 example/android/app/src/main/res/mipmap-mdpi/ic_launcher.png
@@ -110,7 +112,6 @@ e14aa40904929bf313fded22cf7e7ffcbf1d1aac4263b5ef1be8bfce650397aa example/androi
e246ed229511a24a1ee7e98529c203ef90d1d352290ce8486caebe05683db3a0 env.sh
e677d701ffe4af7bc2935098d6b3984cc9ab7ace573e6900955a5535b12410cf example/ios/Runner/Assets.xcassets/AppIcon.appiconset/[email protected]
e789cd4d1bed8a78ec8014c5c5913e300f81b63ea56a56aacb0dfec3b5e7ce2b .flutter-version
-f40c8521b0cc5668568ff5a960ec1deab573cb60a95d5450e205ce35d08777d5 example/README.md
fbbda2e7e29bbd860539a9ca18c478f3b02de140f25a872c19a6dbecd11bc94b .github/workflows/publish.yml
fcef63e72b69415a1090c376095f8f44977e26104ffaeccf3a82430f65dcd4ff lib/src/errors.dart
fd2bad0ad87fbf2f15f7e9845b830db58408bb4c502c6ff105f39e4e7cce1905 test/multipart_upload_test.dart
diff --git a/example/README.md b/example/README.md
index 303df18..b9d7118 100644
--- a/example/README.md
+++ b/example/README.md
@@ -1,17 +1,376 @@
-# vmodal_example
+# VModal Flutter example
-A new Flutter project.
+This small application shows the basic VModal SDK workflow on Android or iOS:
-## Getting Started
+1. Create a client with a runtime API key.
+2. Confirm which user is authenticated.
+3. Search videos with a natural-language query.
+4. Upload the bundled 10-frame sample video while displaying progress.
+5. Cancel an upload if needed.
-This project is a starting point for a Flutter application.
+The example is intentionally simple. It keeps all UI and SDK calls in
+[`lib/main.dart`](lib/main.dart), so a beginner can follow the complete flow in
+one file.
-A few resources to get you started if this is your first Flutter project:
+## What you need
-- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter)
-- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources)
+Before starting, prepare:
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+- A macOS or Linux computer. The repository installer supports macOS on Intel
+ and Apple Silicon, and Linux on x64.
+- Git, Bash, `curl`, and either `unzip` or `tar`.
+- Android Studio with an Android emulator, or a connected Android phone.
+- For iOS, a Mac with Xcode and an iOS simulator or connected iPhone.
+- A valid VModal runtime API key supplied by your authenticated application or
+ VModal administrator.
+
+You do not need to install Flutter globally. The repository can download and
+use its reviewed Flutter version (`3.44.6`) from a user-owned cache.
+
+> Never commit an API key, place it in Flutter assets, print it in logs, or
+> include it directly in source code. This example asks for the key at runtime
+> and keeps it in memory only.
+
+## 1. Open the SDK directory
+
+Run the following commands from the Flutter SDK directory—the directory that
+contains `install.sh`, `run.sh`, and this `example/` folder.
+
+From the VModal monorepo root:
+
+```bash
+cd uinterface/sdk_flutter
+```
+
+If you cloned the Flutter SDK as a standalone repository:
+
+```bash
+cd vmodal_sdk_flutter
+```
+
+## 2. Install the reviewed Flutter toolchain
+
+```bash
+bash install.sh install
+```
+
+This command:
+
+- reads the required version from `.flutter-version`;
+- uses an existing matching Flutter installation when available;
+- otherwise downloads Flutter into `~/.cache/vmodal/flutter`;
+- verifies the downloaded archive checksum; and
+- downloads the Dart dependencies for the SDK package.
+
+Check the installation at any time with:
+
+```bash
+bash install.sh check
+```
+
+The first installation can take several minutes because Flutter and package
+dependencies must be downloaded.
+
+## 3. Start a phone or emulator
+
+Choose one of these options:
+
+### Android emulator
+
+1. Open Android Studio.
+2. Open **Device Manager**.
+3. Create a virtual device if none exists.
+4. Start the virtual device and wait for its home screen.
+
+For a physical Android phone, enable Developer options and USB debugging, then
+connect the phone by USB and approve the computer on the phone.
+
+### iOS simulator
+
+1. Open Xcode once so it can finish installing its components.
+2. Open **Xcode > Open Developer Tool > Simulator**.
+3. Wait for the simulated iPhone home screen.
+
+iOS development requires macOS. A physical iPhone may also require Apple code
+signing; the simulator is usually easier for a first run.
+
+## 4. Find the device ID
+
+The project helper locates the reviewed Flutter binary for you:
+
+```bash
+flutter_bin="$(bash install.sh flutter_bin)"
+"$flutter_bin" devices
+```
+
+Example output may include IDs such as:
+
+```text
+emulator-5554 android
+iPhone 16 Pro ios
+```
+
+Copy the device ID from the middle column. The exact name or ID on your
+computer will be different.
+
+If no mobile device appears, make sure the emulator or simulator has fully
+started, then run the command again. Ignore Chrome because this SDK example
+does not support Flutter Web.
+
+## 5. Run the example
+
+Replace `DEVICE_ID` with the ID shown by the previous command:
+
+```bash
+bash run.sh example --device DEVICE_ID
+```
+
+For example:
+
+```bash
+bash run.sh example --device emulator-5554
+```
+
+Flutter resolves the example's dependencies, builds the application, installs
+it on the selected device, and opens it. The first Android or iOS build is
+usually slower than later builds.
+
+Keep this terminal open while developing:
+
+- Press `r` for hot reload.
+- Press `R` for a full hot restart.
+- Press `q` to stop the app.
+
+## 6. Configure the VModal client
+
+When the application opens:
+
+1. Paste a valid runtime API key into **Runtime API key**.
+2. Tap **Configure client**.
+3. Check the status message at the bottom of the screen.
+
+The expected status is:
+
+```text
+Client configured. Resolve identity or search next.
+```
+
+The input is obscured, and the example clears the text field after creating
+the client. The key remains only in `MutableApiKeyProvider` memory while the
+application is running.
+
+## 7. Confirm authentication
+
+Tap **Resolve auth.me**.
+
+The example calls:
+
+```dart
+final me = await client.auth.me();
+```
+
+A successful request displays the authenticated user type. If you receive an
+SDK error instead, check that the key is valid, has not expired, and belongs to
+the intended VModal environment.
+
+## 8. Run a search
+
+1. Leave the default query, `red bicycle`, or enter your own description.
+2. Tap **Search**.
+3. Read the result count in the status area.
+
+The example sends:
+
+```dart
+final result = await client.searches.searchVideo(
+ SearchRequest(queryText: query),
+);
+```
+
+A result count of zero is still a successful request; it only means the user's
+current video collection has no matching items.
+
+## 9. Upload the bundled sample video
+
+The repository includes
+[`asset/video_10frames.mp4`](asset/video_10frames.mp4), a one-second, 320 × 240
+H.264 video with exactly 10 frames of moving colored zebra stripes. It is small
+enough to use as a quick upload example.
+
+At startup, the example reads this Flutter asset, copies it to the app's
+temporary directory, and fills **App-accessible file path** with the copied
+file's absolute path. This copy is necessary because the upload SDK accepts a
+`File`, while a bundled Flutter asset is not directly exposed as a normal
+mobile file.
+
+To try it:
+
+1. Wait until the status says **Bundled 10-frame sample video is ready.**
+2. Configure the client if you have not already done so.
+3. Leave the pre-filled path unchanged.
+4. Tap **Upload**.
+5. Watch the progress bar and final status message.
+6. Tap **Cancel** while an upload is running to test cancellation. The sample
+ is very small, so it may finish before you can cancel it.
+
+The upload is stored under:
+
+```text
+collection: flutter_example
+sub-collection: astream
+```
+
+To upload your own video instead, replace the pre-filled value with an absolute
+path returned by a file picker, camera flow, downloaded file, or app-owned
+documents/cache directory. A path on your computer is normally not valid
+inside an Android emulator, Android phone, iOS simulator, or iPhone. The mobile
+app must be able to read the file in its own environment.
+
+This example does not include a file-picker package because file picking
+belongs to the parent application.
+
+In a real application, pass the path returned by your chosen picker or camera
+adapter to:
+
+```dart
+final task = client.collections.videoUpload(
+ UploadSource.fromFile(File(path)),
+ collectionName: 'flutter_example',
+ subCollectionName: 'astream',
+);
+```
+
+The SDK streams the file instead of loading the complete video into memory.
+`task.progress` reports upload progress, `task.result` completes with the
+server response, and `task.cancel()` cancels the operation.
+
+## 10. Stop and clean up
+
+Press `q` in the terminal to stop `flutter run`.
+
+The example's `dispose()` method demonstrates the cleanup expected when its
+screen is removed:
+
+- cancel an active upload;
+- cancel the progress subscription;
+- clear the in-memory API key;
+- close the VModal HTTP client; and
+- dispose the text controllers.
+
+For logout or account switching in a production app, cancel active operations,
+clear the credential provider, close the client, and create a new client for
+the next identity.
+
+## How the example is connected to the SDK
+
+The example uses the SDK source from the parent directory rather than a
+published package:
+
+```yaml
+dependencies:
+ vmodal_sdk_flutter:
+ path: ..
+```
+
+This line in [`pubspec.yaml`](pubspec.yaml) means changes made to the SDK's
+`lib/` directory are immediately available to the example after Flutter
+refreshes dependencies.
+
+The main learning points in [`lib/main.dart`](lib/main.dart) are:
+
+- `MutableApiKeyProvider` stores the current runtime credential in memory.
+- `VmodalClient` provides typed SDK resources.
+- `client.auth.me()` resolves the current identity.
+- `client.searches.searchVideo()` performs natural-language video search.
+- `client.collections.videoUpload()` creates a cancellable upload task.
+- `rootBundle.load()` copies the bundled sample into a temporary `File`.
+- `SdkException` provides SDK and API error details.
+
+## Validate the example without a live API key
+
+From the SDK directory, run:
+
+```bash
+bash build.sh pub_get
+bash build.sh analyze
+bash build.sh test
+```
+
+These commands install dependencies, analyze the SDK and example, and run their
+offline tests. They do not require a live VModal API key.
+
+To build the example without launching it:
+
+```bash
+bash build.sh example_android
+```
+
+On a configured Mac, build the iOS simulator application with:
+
+```bash
+bash build.sh example_ios
+```
+
+## Troubleshooting
+
+### `Pinned Flutter 3.44.6 is not installed`
+
+Run:
+
+```bash
+bash install.sh install
+```
+
+### No device is available
+
+Start the emulator or simulator, unlock it, and check again:
+
+```bash
+flutter_bin="$(bash install.sh flutter_bin)"
+"$flutter_bin" devices
+```
+
+For Android, also check that Android Studio has installed an Android SDK and
+that a physical phone has approved USB debugging.
+
+### `Configure the client first`
+
+Enter the runtime API key and tap **Configure client** before using identity,
+search, or upload actions.
+
+### Authentication or network error
+
+Check the status text at the bottom of the application. Confirm that:
+
+- the key is valid and not expired;
+- the device has internet access;
+- the key belongs to the correct backend environment; and
+- the VModal service is reachable from the device.
+
+### `Select an app-accessible file first`
+
+The path is empty, the file does not exist on the mobile device, or the app
+cannot read it. Do not use a normal desktop path for a file that has not been
+copied or selected inside the device environment.
+
+### Dependency or generated-file errors
+
+Refresh both the SDK and example dependencies:
+
+```bash
+bash build.sh pub_get
+```
+
+If old build output is causing a problem, clean and retry:
+
+```bash
+bash test.sh clean
+bash build.sh pub_get
+```
+
+## Next steps
+
+- Read the [SDK guide](../docs/sdk_doc.md).
+- Learn how to [manage API keys](../docs/manage_api_key.md).
+- Follow the [search application guide](../docs/search_app.md).
+- Review the [SDK contract](../docs/sdk_contract.md).
diff --git a/example/asset/video_10frames.mp4 b/example/asset/video_10frames.mp4
new file mode 100644
index 0000000..2dd15f4
Binary files /dev/null and b/example/asset/video_10frames.mp4 differ
diff --git a/example/lib/main.dart b/example/lib/main.dart
index e1c1615..4c01df4 100644
--- a/example/lib/main.dart
+++ b/example/lib/main.dart
@@ -2,6 +2,7 @@ import 'dart:async';
import 'dart:io';
import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';
void main() => runApp(const VmodalExampleApp());
@@ -14,6 +15,7 @@ class VmodalExampleApp extends StatefulWidget {
}
class _VmodalExampleAppState extends State<VmodalExampleApp> {
+ static const _sampleAsset = 'asset/video_10frames.mp4';
final _key = TextEditingController();
final _query = TextEditingController(text: 'red bicycle');
final _path = TextEditingController();
@@ -26,6 +28,26 @@ class _VmodalExampleAppState extends State<VmodalExampleApp> {
int _progress = 0;
bool _busy = false;
+ @override
+ void initState() {
+ super.initState();
+ unawaited(_prepareSample());
+ }
+
+ Future<void> _prepareSample() async {
+ final data = await rootBundle.load(_sampleAsset);
+ final file = File('${Directory.systemTemp.path}/video_10frames.mp4');
+ final bytes = data.buffer.asUint8List(
+ data.offsetInBytes,
+ data.lengthInBytes,
+ );
+ await file.writeAsBytes(bytes, flush: true);
+ _safeState(() {
+ _path.text = file.path;
+ _status = 'Bundled 10-frame sample video is ready.';
+ });
+ }
+
Future<void> _connect() async {
final value = _key.text.trim();
if (value.isEmpty) {
@@ -174,7 +196,7 @@ class _VmodalExampleAppState extends State<VmodalExampleApp> {
controller: _path,
decoration: const InputDecoration(
labelText: 'App-accessible file path',
- helperText: 'A picker adapter belongs to the parent app.',
+ helperText: 'The bundled 10-frame sample is preloaded.',
),
),
LinearProgressIndicator(value: _progress / 100),
diff --git a/example/pubspec.yaml b/example/pubspec.yaml
index 6b821ca..95aa48d 100644
--- a/example/pubspec.yaml
+++ b/example/pubspec.yaml
@@ -59,6 +59,9 @@ flutter:
# the material Icons class.
uses-material-design: true
+ assets:
+ - asset/video_10frames.mp4
+
# To add assets to your application, add an assets section, like this:
# assets:
# - images/a_dot_burr.jpeg