Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.videodb.io/llms.txt

Use this file to discover all available pages before exploring further.

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