Skip to main content

Large File Upload (TUS Protocol)

Upload large audio/video files using the TUS resumable upload protocol.

Overview​

The Scriptix API uses TUS protocol for large file uploads, providing:

  • Resumable uploads - Continue after network interruptions
  • Chunked upload - Files sent in 50MB chunks
  • Progress tracking - Monitor upload progress
  • Large file support - Handle files that exceed standard upload limits

TUS Endpoint​

POST /api/v3/files/

Base URL: https://api.scriptix.io/api/v3/files/

Authentication​

All TUS uploads require Bearer token authentication:

Authorization: Bearer YOUR_TOKEN

Upload Configuration​

Chunk Size​

  • Default: 50MB (52,428,800 bytes)
  • Recommended: 50MB for optimal performance

Retry Strategy​

Automatic retry with exponential backoff:

  • Delays: 0ms, 3s, 5s, 10s, 20s, 30s, 60s
  • Automatically resumes interrupted uploads

Fingerprinting​

Files are fingerprinted for resume capability:

tus-{filename}-{filetype}-{filesize}-{uuid}

Implementation Examples​

JavaScript with @uppy/tus​

npm install @uppy/core @uppy/tus
import Uppy from '@uppy/core';
import Tus from '@uppy/tus';

const uppy = new Uppy({
  restrictions: {
    maxTotalFileSize: 10 * 1024 * 1024 * 1024, // 10GB max
    allowedFileTypes: ['video/*', 'audio/*']
  }
})
.use(Tus, {
  endpoint: 'https://api.scriptix.io/api/v3/files/',
  retryDelays: [0, 3000, 5000, 10000, 20000, 30000, 60000],
  chunkSize: 50 * 1024 * 1024, // 50MB chunks
  headers: {
    Authorization: 'Bearer YOUR_TOKEN'
  },
  withCredentials: true,
  removeFingerprintOnSuccess: false,
  storeFingerprintForResuming: true
});

// Add file
uppy.addFile({
  name: 'large-video.mp4',
  type: 'video/mp4',
  data: fileBlob
});

// Upload
uppy.upload();

// Track progress
uppy.on('progress', (progress) => {
  console.log(`Upload progress: ${progress}%`);
});

// Handle completion
uppy.on('complete', (result) => {
  console.log('Upload complete:', result);
});

Python with tuspy​

pip install tuspy
from tusclient import client

# Configure TUS client
tus_client = client.TusClient('https://api.scriptix.io/api/v3/files/')

# Create uploader
uploader = tus_client.uploader(
    file_path='large-video.mp4',
    chunk_size=52428800,  # 50MB chunks
    headers={
        'Authorization': 'Bearer YOUR_TOKEN'
    },
    metadata={
        'filename': 'large-video.mp4',
        'filetype': 'video/mp4'
    }
)

# Upload with progress tracking
def on_progress(bytes_uploaded, bytes_total):
    percentage = (bytes_uploaded / bytes_total) * 100
    print(f"Upload progress: {percentage:.2f}%")

uploader.upload(on_progress=on_progress)
print("Upload complete!")

Node.js with tus-js-client​

npm install tus-js-client
const tus = require('tus-js-client');
const fs = require('fs');

const file = fs.createReadStream('large-video.mp4');
const fileSize = fs.statSync('large-video.mp4').size;

const upload = new tus.Upload(file, {
  endpoint: 'https://api.scriptix.io/api/v3/files/',
  chunkSize: 50 * 1024 * 1024, // 50MB
  retryDelays: [0, 3000, 5000, 10000, 20000, 30000, 60000],
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  metadata: {
    filename: 'large-video.mp4',
    filetype: 'video/mp4'
  },
  onProgress: (bytesUploaded, bytesTotal) => {
    const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
    console.log(`Uploaded ${percentage}%`);
  },
  onSuccess: () => {
    console.log('Upload complete!');
    console.log('Upload URL:', upload.url);
  },
  onError: (error) => {
    console.error('Upload failed:', error);
  }
});

// Start upload
upload.start();

// To pause upload
// upload.abort();

// To resume upload
// upload.start();

Resume Interrupted Uploads​

TUS protocol automatically handles resume:

import Uppy from '@uppy/core';
import Tus from '@uppy/tus';

const uppy = new Uppy()
  .use(Tus, {
    endpoint: 'https://api.scriptix.io/api/v3/files/',
    chunkSize: 50 * 1024 * 1024,
    headers: {
      Authorization: 'Bearer YOUR_TOKEN'
    },
    // Enable resume functionality
    removeFingerprintOnSuccess: false,
    storeFingerprintForResuming: true,
    // Fingerprint function for unique file identification
    fingerprint: (file) => {
      return Promise.resolve(
        `tus-${file.name}-${file.type}-${file.size}-${generateUUID()}`
      );
    }
  });

// If upload is interrupted, calling upload() again will resume
uppy.upload();

After Upload Completes​

Once the TUS upload finishes, the file is automatically queued for transcription. You can then:

1. Check Processing Status​

Use the session ID from your upload to check status:

GET /api/v3/speech-to-text/session/{sessionId}

See Batch API Overview for details.

2. Retrieve Results​

Once processing completes:

GET /api/v3/speech-to-text/session/{sessionId}/document/{documentId}

See Retrieve Results for details.

Best Practices​

chunkSize: 50 * 1024 * 1024  // 50MB - optimal for most networks

2. Implement Progress Tracking​

uppy.on('progress', (progress) => {
  // Update UI with upload progress
  updateProgressBar(progress);
});

3. Handle Errors Gracefully​

uppy.on('error', (error) => {
  console.error('Upload error:', error);
  // Retry or show error to user
});

4. Enable Resume for Large Files​

removeFingerprintOnSuccess: false,
storeFingerprintForResuming: true

5. Set Appropriate Timeouts​

retryDelays: [0, 3000, 5000, 10000, 20000, 30000, 60000]

Troubleshooting​

Upload Fails Immediately​

  • Check: Valid Bearer token in Authorization header
  • Check: File size within limits
  • Check: Correct endpoint URL

Upload Stalls​

  • Solution: Automatic retry will handle this
  • Alternative: Manually pause and resume upload

Cannot Resume Upload​

  • Check: storeFingerprintForResuming: true is set
  • Check: Using consistent fingerprint function
  • Check: Browser/client localStorage not cleared

Supported File Formats​

Audio​

  • MP3, WAV, FLAC, M4A, AAC, OGG

Video​

  • MP4, MOV, AVI, MKV, WEBM

File Size Limits​

  • Standard Upload: Up to 500MB
  • TUS Upload: Recommended for files > 500MB
  • Maximum: Check your plan limits

TUS Protocol: Official TUS Specification