V- Modal AI: Visual Video / Image Search - Flutter Video SDK
Dart android-sdkflutterflutter-appflutter-packageflutter-sdkflutter-videoflutter-video-editingflutter-video-playerflutter-video-sdkflutter-videosflutter-videosdkmobile-videomobile-video-editor-sdkmobile-video-sdkvideo-editingvideo-sdkvideo-searchvideo-search-enginevideo-streaming
import 'dart:io';
import 'dart:math';
import 'dart:typed_data';
import 'errors.dart';
import 'http.dart';
import 'models.dart';
import 'routes.dart';
import 'transport.dart';
import 'upload.dart';
import 'utils.dart';
/// Authentication, identity, and service-health operations.
class AuthResource {
/// @nodoc
AuthResource(this.http);
/// @nodoc
final VmodalHttp http;
/// Returns service health metadata.
Future<HealthResponse> health({CancellationToken? cancellation}) async =>
HealthResponse(
await http.request(
'GET',
Routes.full(Routes.health),
cancellation: cancellation,
),
);
/// Returns `true` when the authenticated health check completes.
Future<bool> authCheck({CancellationToken? cancellation}) async {
await health(cancellation: cancellation);
return true;
}
/// Resolves the profile associated with the current API key.
Future<UserProfile> me({CancellationToken? cancellation}) async =>
UserProfile(
await http.requestUsers(
'GET',
Routes.usersFull(Routes.authMe),
cancellation: cancellation,
),
);
}
/// Multimodal media-search operations.
class SearchesResource {
/// @nodoc
SearchesResource(this.http);
/// @nodoc
final VmodalHttp http;
/// Validates [request] and returns matching media results.
///
/// Use [CancellationToken.cancel] when the owning screen is disposed or a
/// newer query supersedes this one.
Future<SearchResponse> searchVideo(
SearchRequest request, {
CancellationToken? cancellation,
}) async {
request.validate();
return SearchResponse(
await http.request(
'POST',
Routes.full(Routes.searchClient),
json: request.toJson(),
cancellation: cancellation,
),
);
}
/// Runs [batchQueryInput] through [searchVideo] with bounded concurrency.
///
/// Each worker processes contiguous mini-batches of [batchSize] requests
/// serially. At most [nWorker] searches are in flight, and results retain
/// their input order. The caller owns [cancellation] and may share it with
/// other operations.
Future<List<SearchResponse>> searchBatch(
List<SearchRequest> batchQueryInput, {
int batchSize = 10,
int nWorker = 4,
CancellationToken? cancellation,
}) async {
if (batchSize <= 0) {
throw const ValidationException('batchSize must be greater than zero');
}
if (nWorker <= 0) {
throw const ValidationException('nWorker must be greater than zero');
}
final requests = List<SearchRequest>.of(batchQueryInput, growable: false);
for (final request in requests) {
request.validate();
}
if (requests.isEmpty) return <SearchResponse>[];
final results = List<SearchResponse?>.filled(requests.length, null);
final failures = <_BatchFailure>[];
var nextStart = 0;
var stopped = false;
void recordFailure(int index, Object error, StackTrace stackTrace) {
failures.add(_BatchFailure(index, error, stackTrace));
stopped = true;
}
Future<void> worker() async {
while (true) {
if (stopped) return;
try {
cancellation?.throwIfCanceled();
} on Object catch (error, stackTrace) {
recordFailure(nextStart, error, stackTrace);
return;
}
if (stopped || nextStart >= requests.length) return;
final start = nextStart;
final end = min(start + batchSize, requests.length);
nextStart = end;
for (var index = start; index < end; index++) {
if (stopped) return;
try {
cancellation?.throwIfCanceled();
results[index] = await searchVideo(
requests[index],
cancellation: cancellation,
);
} on Object catch (error, stackTrace) {
recordFailure(index, error, stackTrace);
return;
}
}
}
}
final batchCount = (requests.length + batchSize - 1) ~/ batchSize;
await Future.wait(<Future<void>>[
for (var index = 0; index < min(nWorker, batchCount); index++) worker(),
]);
if (failures.isNotEmpty) {
failures.sort(
(_BatchFailure left, _BatchFailure right) =>
left.index.compareTo(right.index),
);
final failure = failures.first;
Error.throwWithStackTrace(failure.error, failure.stackTrace);
}
return <SearchResponse>[for (final result in results) result!];
}
}
final class _BatchFailure {
const _BatchFailure(this.index, this.error, this.stackTrace);
final int index;
final Object error;
final StackTrace stackTrace;
}
/// Collection discovery, mutation, and media-upload operations.
class CollectionsResource {
/// @nodoc
CollectionsResource(this.http, this.signedUploads);
/// @nodoc
final VmodalHttp http;
/// @nodoc
final SignedUploadTransport signedUploads;
/// Lists collections, optionally filtered by [mode].
Future<GroupsResponse> listGroups({
String? mode,
CancellationToken? cancellation,
}) async => GroupsResponse(
await http.request(
'GET',
Routes.full(Routes.groups),
params: <String, Object?>{if (mode != null) 'mode': mode},
cancellation: cancellation,
),
);
/// Uploads a small file as one SDK request.
///
/// Prefer [CollectionUploads.videoUpload] for signed uploads with progress
/// and cancellation.
Future<UploadResponse> uploadFile(
VmodalFilePart part, {
String groupName = '',
String mode = 'vid_file',
String streamName = 'astream',
String description = '',
List<String> tag = const <String>[],
String? videoFilename,
String? metadataText,
List<String>? metadataTags,
String? startDatetimeUser,
bool reProcess = false,
CancellationToken? cancellation,
}) async {
validateCctvUpload(
mode: mode,
sourceFileName: part.fileName,
videoFilename: videoFilename,
startDatetimeUser: startDatetimeUser,
);
final publicName = strCctvVideoFilename(
part.fileName,
videoFilename,
startDatetimeUser,
);
return UploadResponse(
await http.request(
'POST',
Routes.full(Routes.upload),
data: <String, Object?>{
'mode': mode,
'group_name': groupName,
'stream_name': streamName,
'description': description,
if (tag.isNotEmpty) 'tag': tag,
if (publicName != null) 'video_filename': publicName,
if (metadataText != null) 'metadata_text': metadataText,
if (metadataTags != null) 'metadata_tags': metadataTags,
if (startDatetimeUser != null)
'start_datetime_user': startDatetimeUser,
're_process': reProcess,
},
files: <VmodalFilePart>[part],
cancellation: cancellation,
),
);
}
/// Always throws [FeatureDisabled] before any transport call.
Never uploadFolder() => throw const FeatureDisabled(
'folder upload is disabled on server (cannot scan remote PC/laptop)',
);
/// Uploads JSON Lines metadata and returns the accepted metadata result.
Future<MetadataParquetUploadResponse> uploadMetadataJsonl(
VmodalFilePart part, {
String mode = 'img_file',
String groupName = '',
String streamName = '',
String writeMode = 'append',
bool allowOverlap = false,
CancellationToken? cancellation,
}) async {
final form = <String, Object?>{
'mode': mode,
'group_name': groupName,
'stream_name': streamName,
'write_mode': writeMode,
'allow_overlap': '$allowOverlap',
if (http.config.normalizedMode == 'direct')
'user_id': http.config.normalizedUserId,
};
Map<String, Object?> raw;
try {
raw = await http.request(
'POST',
Routes.full(Routes.uploadMetadataJsonl),
data: form,
files: <VmodalFilePart>[part],
cancellation: cancellation,
);
} on ApiException catch (error) {
if (error.statusCode != 404) rethrow;
raw = await http.request(
'POST',
Routes.uploadMetadataItemParquetInternal,
data: form,
files: <VmodalFilePart>[part],
cancellation: cancellation,
);
}
return MetadataParquetUploadResponse(raw);
}
/// Adds existing [assetIds] to a collection after local validation.
Future<CollectionAddAssetsResponse> addAssets({
required String collectionId,
required List<String> assetIds,
required String mode,
required String groupName,
String streamName = 'astream',
CancellationToken? cancellation,
}) async {
final request = CollectionAddAssetsRequest(
collectionId: collectionId,
assetIds: assetIds,
mode: mode,
groupName: groupName,
streamName: streamName,
);
request.validate();
final path = Routes.collectionAddAssets.replaceAll(
'{collection_id}',
Uri.encodeComponent(collectionId),
);
return CollectionAddAssetsResponse(
await http.request(
'POST',
Routes.full(path),
json: request.toJson(),
cancellation: cancellation,
),
);
}
/// Updates the description and/or tags for one collection item.
Future<CollectionDescriptionUpdateResponse> updateDescription({
required String groupName,
required String mode,
required String streamName,
required String filenameSanitized,
String? description,
List<String>? tag,
CancellationToken? cancellation,
}) async => CollectionDescriptionUpdateResponse(
await http.request(
'POST',
Routes.full(Routes.collectionDescriptionUpdate),
data: <String, Object?>{
'group_name': groupName,
'mode': mode,
'stream_name': streamName,
'filename_sanitized': filenameSanitized,
if (description != null) 'description': description,
if (tag != null) 'tag': tag,
},
cancellation: cancellation,
),
);
/// Deletes collection data according to [scope].
///
/// Use [dryRun] to inspect the operation before setting [confirm] for a
/// destructive deletion.
Future<DeleteCollectionResponse> delete({
required String groupName,
required String mode,
String scope = 'all',
bool dryRun = false,
bool confirm = false,
CancellationToken? cancellation,
}) async {
final request = DeleteCollectionRequest(
groupName: groupName,
mode: mode,
scope: scope,
dryRun: dryRun,
confirm: confirm,
);
request.validate();
return DeleteCollectionResponse(
await http.request(
'DELETE',
Routes.full(Routes.collectionDelete),
json: request.toJson(),
cancellation: cancellation,
),
);
}
/// Always throws [FeatureDisabled]; uploads create collections implicitly.
Never create() => throw const FeatureDisabled(
'no server endpoint; upload creates collection implicitly',
);
/// Always throws [FeatureDisabled]; collection editing is not available.
Never edit() => throw const FeatureDisabled(
'no server endpoint; upload creates collection implicitly',
);
/// Always throws [FeatureDisabled] before any transport call.
Never autoIndexGet() => throw const FeatureDisabled(
'collection auto_index is disabled on server',
);
/// Always throws [FeatureDisabled] before any transport call.
Never autoIndexSet() => throw const FeatureDisabled(
'collection auto_index is disabled on server',
);
}
/// Index lifecycle operations for searchable collections.
class IndexesResource {
/// @nodoc
IndexesResource(this.http);
/// @nodoc
final VmodalHttp http;
/// Lists index jobs with optional filters.
///
/// [limit] must be between 1 and 1000.
Future<IndexationJobsListResponse> jobsList({
String? status,
String? mode,
String? groupName,
int limit = 200,
CancellationToken? cancellation,
}) async {
if (limit < 1 || limit > 1000) {
throw const ValidationException('limit must be between 1 and 1000');
}
return IndexationJobsListResponse(
await http.request(
'GET',
Routes.full(Routes.indexationJobs),
params: <String, Object?>{
'limit': limit,
if (status != null) 'status': status,
if (mode != null) 'mode': mode,
if (groupName != null) 'group_name': groupName,
},
cancellation: cancellation,
),
);
}
/// Validates and starts an indexation job.
Future<IndexationSubmitResponse> createIndex(
IndexationSubmitRequest request, {
CancellationToken? cancellation,
}) async {
request.validate();
return IndexationSubmitResponse(
await http.request(
'POST',
Routes.full(Routes.indexationSubmit),
json: request.toJson(),
cancellation: cancellation,
),
);
}
/// Returns the latest known state for [jobId].
Future<IndexationStatusResponse> indexStatus(
String jobId, {
CancellationToken? cancellation,
}) async {
final clean = strRequired(jobId, 'job_id');
final path = Routes.indexationStatus.replaceAll(
'{job_id}',
Uri.encodeComponent(clean),
);
try {
return IndexationStatusResponse(
await http.request(
'GET',
Routes.full(path),
cancellation: cancellation,
),
);
} on ApiException catch (error) {
if (error.statusCode != 404) rethrow;
final jobs = await jobsList(limit: 1000, cancellation: cancellation);
final row = objectList(jobs.raw['data'])
.where((Map<String, Object?> value) => '${value['job_id']}' == clean)
.firstOrNull;
if (row == null) rethrow;
return IndexationStatusResponse(row);
}
}
/// Validates and deletes the selected index data.
Future<IndexationDeleteResponse> deleteIndex(
IndexationDeleteRequest request, {
CancellationToken? cancellation,
}) async {
request.validate();
return IndexationDeleteResponse(
await http.request(
'DELETE',
Routes.full(Routes.indexationDelete),
json: request.toJson(),
cancellation: cancellation,
),
);
}
/// Always throws [FeatureDisabled] before any transport call.
Never embeddingModels() => throw const FeatureDisabled(
'embedding models endpoint is disabled on server',
);
}
/// Usage and operational-statistics queries for the active identity.
class AdminResource {
/// @nodoc
AdminResource(this.http);
/// @nodoc
final VmodalHttp http;
/// Returns user-level search statistics.
Future<AdminUserStatsResponse> userStats({
CancellationToken? cancellation,
}) async => AdminUserStatsResponse(
await http.request(
'GET',
Routes.full(Routes.adminUserStats),
cancellation: cancellation,
),
);
/// Returns usage for [date], or the service default period when blank.
Future<UsageUserDetail> usage({
String date = '',
CancellationToken? cancellation,
}) async => UsageUserDetail(
await http.requestUsers(
'GET',
Routes.usersFull(Routes.adminUsage),
params: <String, Object?>{
if (date.trim().isNotEmpty) 'date': date.trim(),
},
cancellation: cancellation,
),
);
/// Returns current cache and limiter statistics.
Future<CacheStats> cacheStats({CancellationToken? cancellation}) async =>
CacheStats(
await http.requestUsers(
'GET',
Routes.usersFull(Routes.adminCacheStats),
cancellation: cancellation,
),
);
}
/// Advanced signed object-upload preparation operations.
class R2Resource {
/// @nodoc
R2Resource(this.http);
/// @nodoc
final VmodalHttp http;
/// Creates a temporary upload grant for one file.
Future<PresignedUploadResponse> presignUploadFile({
required String mode,
required String groupName,
required String streamName,
required String modality,
required String filename,
int expiresIn = 900,
CancellationToken? cancellation,
}) async => PresignedUploadResponse(
await http.requestUsers(
'GET',
Routes.usersFull(Routes.r2UploadFile),
params: <String, Object?>{
'mode': mode,
'group_name': groupName,
'stream_name': streamName,
'modality': modality,
'filename': filename,
'expires_in': expiresIn,
},
cancellation: cancellation,
),
);
/// Creates temporary upload grants for all [filenames].
Future<PresignedFolderResponse> presignUploadFolderVideo({
required String mode,
required String groupName,
required String streamName,
required List<String> filenames,
int expiresIn = 900,
CancellationToken? cancellation,
}) async => PresignedFolderResponse(
await http.requestUsers(
'POST',
Routes.usersFull(Routes.r2UploadFolderVideo),
json: <String, Object?>{
'mode': mode,
'group_name': groupName,
'stream_name': streamName,
'filenames': filenames,
'expires_in': expiresIn,
},
cancellation: cancellation,
),
);
}
/// Image-location and image-download operations.
class ImagesResource {
/// @nodoc
ImagesResource(this.http);
/// @nodoc
final VmodalHttp http;
/// Resolves a temporary URL for one stored image.
Future<ImageUrlResponse> getUrl({
required String mode,
required String groupName,
required String modality,
required String filename,
String streamName = 'astream',
Object? tsUnix13digits,
String? userid,
CancellationToken? cancellation,
}) async => ImageUrlResponse(
await http.request(
'POST',
Routes.full(Routes.imageGetUrl),
json: <String, Object?>{
'mode': mode,
'group_name': groupName,
'modality': modality,
'stream_name': streamName,
'filename': filename,
if (tsUnix13digits != null) 'ts_unix_13digits': '$tsUnix13digits',
if (http.config.normalizedMode == 'direct' &&
(userid?.trim().isNotEmpty ?? false))
'userid': userid,
},
cancellation: cancellation,
),
);
/// Resolves image URLs for [records] in one call.
///
/// Identity fields in records are ignored outside direct mode.
Future<ImageUrlBulkResponse> getUrlBulk(
List<Map<String, Object?>> records, {
String? userid,
CancellationToken? cancellation,
}) async {
final safe = http.config.normalizedMode == 'direct'
? records
: records
.map(
(Map<String, Object?> row) => Map<String, Object?>.from(row)
..remove('userid')
..remove('user_id'),
)
.toList();
return ImageUrlBulkResponse(
await http.request(
'POST',
Routes.full(Routes.imageGetUrlBulk),
json: <String, Object?>{
'records': safe,
if (http.config.normalizedMode == 'direct' &&
(userid?.trim().isNotEmpty ?? false))
'userid': userid,
},
cancellation: cancellation,
),
);
}
/// Downloads image bytes from a previously returned temporary URL.
Future<Uint8List> getImageFromUrl(
String urlPreSigned, {
String? userid,
int? maxBytes,
CancellationToken? cancellation,
}) => http.requestBytes(
'POST',
Routes.full(Routes.imageGetImage),
json: <String, Object?>{
'url_pre_signed': urlPreSigned,
if (http.config.normalizedMode == 'direct' &&
(userid?.trim().isNotEmpty ?? false))
'userid': userid,
},
maxBytes: maxBytes,
cancellation: cancellation,
);
/// Streams an image into a caller-owned [sink] without closing it.
Future<void> writeImageFromUrl(
String urlPreSigned,
IOSink sink, {
String? userid,
int? maxBytes,
CancellationToken? cancellation,
}) => http.requestBytesToSink(
'POST',
Routes.full(Routes.imageGetImage),
sink: sink,
json: <String, Object?>{
'url_pre_signed': urlPreSigned,
if (http.config.normalizedMode == 'direct' &&
(userid?.trim().isNotEmpty ?? false))
'userid': userid,
},
maxBytes: maxBytes,
cancellation: cancellation,
);
/// Atomically downloads an image into [destination].
Future<File> saveImageFromUrl(
String urlPreSigned,
File destination, {
String? userid,
int? maxBytes,
CancellationToken? cancellation,
}) async {
final temp = File(
'${destination.path}.${DateTime.now().microsecondsSinceEpoch}-'
'${Random.secure().nextInt(1 << 32)}.tmp',
);
final sink = temp.openWrite();
try {
await writeImageFromUrl(
urlPreSigned,
sink,
userid: userid,
maxBytes: maxBytes,
cancellation: cancellation,
);
await sink.flush();
await sink.close();
await temp.rename(destination.path);
return destination;
} on Object catch (error, stack) {
try {
await sink.close();
} on Object {
// The sink may already be closed after a source-stream error.
}
if (await temp.exists()) await temp.delete();
Error.throwWithStackTrace(error, stack);
}
}
/// Downloads several images represented by [urls].
Future<ImageGetBulkResponse> getImageBulkFromUrls(
List<String> urls, {
String? userid,
CancellationToken? cancellation,
}) async => ImageGetBulkResponse(
await http.request(
'POST',
Routes.full(Routes.imageGetImageBulk),
json: <String, Object?>{
'urls': urls,
if (http.config.normalizedMode == 'direct' &&
(userid?.trim().isNotEmpty ?? false))
'userid': userid,
},
cancellation: cancellation,
),
);
}
/// Disabled Google Drive compatibility surface.
class GDriveResource {
/// Always throws [FeatureDisabled] before any transport call.
Never privateAuthUrl() => throw const FeatureDisabled(
'private google drive auth endpoint is disabled on server',
);
/// Always throws [FeatureDisabled] before any transport call.
Never privateDownload() => throw const FeatureDisabled(
'private google drive download endpoint is disabled on server',
);
}
/// Disabled SQL compatibility surface.
class SqlResource {
/// Always throws [FeatureDisabled] before any transport call.
Never query() =>
throw const FeatureDisabled('sql query endpoint is disabled on server');
}