Skip to main content
If you’re upgrading from v0.1.3, this guide walks you through the two breaking changes you need to address. The migration is straightforward (mostly find-and-replace).

​
What Changed

PatternBefore (v0.1.3)After (v0.2.0)
Property Accessvideo.meta.idvideo.id
Async OperationswaitForJob(video.getTranscript())await video.getTranscript()
UploadsReturns UploadJobReturns Video / Audio / Image directly
Error Handling.on('error', callback)Standard try/catch

​
Breaking Change 1: Direct Property Access

In v0.1.3, all properties were wrapped in a .meta object. In v0.2.0, properties are accessed directly on the instance.

​
Video

const video = await collection.getVideo('m-123');

console.log(video.meta.id);           // 'm-123'
console.log(video.meta.name);         // 'My Video'
console.log(video.meta.streamUrl);    // 'https://stream.videodb.io/...'
console.log(video.meta.playerUrl);    // 'https://console.videodb.io/player?...'
console.log(video.meta.length);       // 120.5
console.log(video.meta.collectionId); // 'c-123'

const url = `https://example.com/video/${video.meta.id}`;

​
Audio

const audio = await collection.getAudio('a-123');

console.log(audio.meta.id);           // 'a-123'
console.log(audio.meta.name);         // 'podcast.mp3'
console.log(audio.meta.length);       // 3600.0
console.log(audio.meta.collectionId); // 'c-123'

​
Image

const image = await collection.getImage('img-123');

console.log(image.meta.id);           // 'img-123'
console.log(image.meta.name);         // 'thumbnail.png'
console.log(image.meta.url);          // 'https://...'
console.log(image.meta.collectionId); // 'c-123'

​
Collection

const collection = await conn.getCollection('c-123');

console.log(collection.meta.id);          // 'c-123'
console.log(collection.meta.name);        // 'My Videos'
console.log(collection.meta.description); // 'Collection description'

const videos = await fetchVideos(collection.meta.id);

​
Shot (Search Results)

const results = await video.search('hello world');

for (const shot of results.shots) {
  console.log(shot.meta.videoId);     // 'm-123'
  console.log(shot.meta.start);       // 10.5
  console.log(shot.meta.end);         // 15.2
  console.log(shot.meta.text);        // 'hello world example'
  console.log(shot.meta.searchScore); // 0.95
}
Migration shortcut: Search your codebase for .meta. and replace with . for each class type.

​
Breaking Change 2: Async/Await Pattern

In v0.1.3, long-running operations returned Job objects that required callback registration. In v0.2.0, these are standard async functions. The SDK handles polling internally, errors propagate through try/catch, and there’s no risk of silent failures from unregistered error handlers.

​
Getting Transcripts

import { waitForJob } from 'videodb';

// Option 1: Using callbacks
const job = video.getTranscript();

job.on('success', (transcript) => {
  console.log('Transcript:', transcript);
});

job.on('error', (err) => {
  console.error('Failed:', err);
});

await job.start();

// Option 2: Using waitForJob helper
const transcript = await waitForJob(video.getTranscript(true));

​
Indexing Spoken Words

import { waitForJob } from 'videodb';

const indexJob = video.indexSpokenWords();

indexJob.on('success', (result) => {
  console.log('Indexing complete:', result.success);
});

indexJob.on('error', (err) => {
  console.error('Indexing failed:', err);
});

await indexJob.start();

​
Uploading Media

import { waitForJob } from 'videodb';

const uploadJob = await collection.uploadFile({
  filePath: '/path/to/video.mp4',
  name: 'My Video',
});

uploadJob.on('success', (video) => {
  console.log('Video ID:', video.meta.id);
});

uploadJob.on('error', (err) => {
  console.error('Upload failed:', err);
});

await uploadJob.start();

​
Error Handling

import { waitForJob } from 'videodb';

const job = video.getTranscript();

job.on('success', (transcript) => {
  console.log('Got transcript:', transcript);
});

job.on('error', (err) => {
  // If you forget this handler, errors are silently logged
  console.error('Transcript failed:', err);
  notifyUser('Could not generate transcript');
});

await job.start();

​
Removed Exports

The following exports no longer exist in v0.2.0: 
// These imports will fail in v0.2.0
import {
  Job, // REMOVED
  TranscriptJob, // REMOVED
  UploadJob, // REMOVED
  IndexJob, // REMOVED
  waitForJob, // REMOVED
} from "videodb";
If your code imports any of these, remove the imports and refactor to use await directly on the method calls.

​
Migration Checklist

​
Property Access

1

Search for .meta. patterns

Use your IDE or grep to find all occurrences of .meta. in your codebase.
2

Replace with direct access

  • video.meta.* → video.* - audio.meta.* → audio.* - image.meta.* → image.* - collection.meta.* → collection.* - shot.meta.* → shot.*

​
Job Pattern

1

Remove Job imports

Delete imports for Job, TranscriptJob, UploadJob, IndexJob, waitForJob
2

Remove callback registrations

Delete .on('success', ...) and .on('error', ...) blocks
3

Remove .start() calls

Delete any job.start() or await job.start() calls
4

Add await to method calls

Change const job = video.getTranscript() to const transcript = await video.getTranscript()
5

Update error handling

Wrap calls in try/catch instead of using .on('error', ...)

​
Complete Example

import { connect, waitForJob } from 'videodb';

async function processVideo() {
  const conn = connect(process.env.VIDEO_DB_API_KEY);
  const collection = await conn.getCollection();

  // Upload
  const uploadJob = await collection.uploadFile({
    filePath: './video.mp4',
    name: 'My Video',
  });
  const video = await waitForJob(uploadJob);
  console.log('Uploaded:', video.meta.id);

  // Transcript
  const transcriptJob = video.getTranscript();
  const transcript = await waitForJob(transcriptJob);

  // Index
  const indexJob = video.indexSpokenWords();
  await waitForJob(indexJob);

  // Search
  const results = await video.search('keyword');
  for (const shot of results.shots) {
    console.log(`${shot.meta.start}s: ${shot.meta.text}`);
  }
}

​
Need Help?

GitHub Issues

Report bugs or ask questions

Discord Community

Get help from the community