v-modal/vmodal_sdk_flutter

VModal for Flutter란?

VModal은 모바일 앱(Android/iOS)에 멀티모달 비디오 검색 및 업로드 기능을 추가할 수 있는 Flutter SDK입니다. VModal 클라우드 서비스에 앱을 연결하여 비디오 콘텐츠를 인덱싱하고 다음을 통해 검색할 수 있게 합니다:

자연어 설명 (예: "빨간 재킷을 입은 자전거 타는 사람")
음성-텍스트 변환(오디오) 및 화면 텍스트
시각적 유사성(이미지 프레임)

SDK는 모든 네트워킹, 스트리밍 업로드, 진행 상황 보고, 취소 토큰 및 타입화된 응답 모델을 처리하며, UI는 완전히 개발자가 제어할 수 있도록 합니다.

핵심 기능

기능	설명
시맨틱 비디오 및 이미지 검색	일반 영어로 비디오 라이브러리를 검색합니다. 결과에는 타임스탬프와 유사도 거리가 포함됩니다.
오디오 및 텍스트 검색	백엔드에서 추출한 음성 또는 화면 캡션을 검색합니다.
스트리밍 업로드	파일 선택기 또는 카메라에서 전체 파일을 메모리에 로드하지 않고 비디오를 직접 업로드합니다. 진행 상황은 Dart `Stream`으로 노출됩니다.
취소	작업별 취소 토큰을 사용하여 화면이 닫힐 때 업로드 또는 검색을 중단할 수 있습니다.
타입화된 API	모든 요청/응답 객체는 Dart에서 강력한 타입으로 제공되어 통합이 간단합니다.
인증 유연성	간단한 런타임 API 키 또는 자체 백엔드에서 얻은 단기 토큰을 사용하여 사용자별 격리를 제공합니다.
세션 및 범위 관리	`VModalProject`를 생성한 다음 컬렉션/스트림(예: 사용자별 라이브러리)으로 `scope`하고 격리된 작업을 수행합니다.
수명 주기 인식	모바일 수명 주기에 맞게 설계되어 자격 증명을 교체하고, 세션을 닫고, 리소스를 결정적으로 정리할 수 있습니다.

시작하기 (빠른 단계)

패키지 추가

dependencies:
  vmodal_sdk_flutter: ^1.2.3   # 또는 pub.dev의 최신 버전

API 키 얻기 – https://v-modal.com/page/contact.ts에서 요청하세요.

Dart 코드에서 SDK 구성:

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',
);

비디오 업로드 (콘솔에 진행 상황 표시):

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}');

업로드된 컬렉션 검색:

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');
}

앱 종료 시 리소스 정리:
```
await project.close();
```

저장소에는 전체 흐름(업로드 → 인덱싱 → 검색 → 이미지 미리보기)을 보여주는 완전한 기능의 예제 앱(example/01_full_app)도 포함되어 있습니다.

일반적인 사용 사례

소비자 비디오 앱 – 사용자가 자연어로 개인 비디오 라이브러리를 검색할 수 있습니다.
보안/CCTV 대시보드 – 카메라 클립을 업로드하고 태그를 지정한 후 객체, 시간 범위 또는 음성 단어로 특정 순간을 검색할 수 있습니다.
전자상거래 제품 비디오 카탈로그 – 제품 데모를 인덱싱하고 쇼핑객이 특정 기능(예: "휴대폰 카메라 모드 보기")을 찾을 수 있게 합니다.
엔터프라이즈 지식 베이스 – 회의 녹화를 저장하고 직원이 키워드나 발표자로 특정 순간을 찾을 수 있게 합니다.

문서 및 지원

API 참조: https://v-modal.github.io/vmodal_sdk_flutter/
Discord 커뮤니티: https://discord.gg/XGxgBQqkaY
Pub.dev 페이지: https://pub.dev/packages/vmodal_sdk_flutter
Reddit 커뮤니티: https://www.reddit.com/r/v_modal/
전체 문서 (인증, 컴포넌트 패턴, 성능 등)는 저장소의 docs/ 폴더에 있습니다.

라이선스

MIT – 상업용 또는 오픈소스 Flutter 앱에서 SDK를 자유롭게 사용, 수정, 배포할 수 있습니다.