File Processing with Samvyo SDK
The Samvyo SDK provides functionality to process MP4 files into HLS (HTTP Live Streaming) format with multiple quality levels, supporting up to 4K (2160p) resolution. This feature allows you to convert your video files into adaptive streaming format, making them suitable for various network conditions and device capabilities.
Important Notes
- Storage Settings Required:
- Storage settings must be configured in the dashboard before processing files
- If storage settings are not provided, processing will fail to upload files
- Important: Processing credits will still be deducted for the amount of processing minutes used, even if the upload fails
- Recommended File Processing Guidelines:
- Ideal Batch Size: Up to 10 files per batch, with each file under 100MB
- Large File Processing: For files larger than 100MB, it's recommended to process them individually
- Batch Processing: For optimal performance and faster processing:
- Process multiple smaller files (under 100MB) in batches of up to 10
- Process larger files (over 100MB) individually
- Multiple batches can be processed in parallel using different servers
Prerequisites
Before using the file processing feature, you need to:
-
Set up your storage configuration in the Samvyo dashboard (opens in a new tab)
-
Navigate to Settings > Storage Settings
-
Configure the following details:
- Cloud Provider: Digital Ocean (currently the only supported provider)
- Bucket Name: Your Digital Ocean bucket name
- Access Key: Your Digital Ocean access key
- Secret Access Key: Your Digital Ocean secret access key
-
(Optional) Configure default output qualities:
- Navigate to Settings > Recording Settings
- Select up to three resolutions that will be used for processing
- If no output qualities are specified here or in the request, the system will use default qualities of [720p, 360p]
Initialization
The file processing feature uses the same SDK instance as room joining. If you have already initialized the SDK for joining a room, you can use that same instance for file processing. If not, you'll need to initialize the SDK first:
import samvyo from "samvyo-js-sdk";
async function initializeSDK() {
const sessionToken = "your-session-token"; // Obtain this from your backend server
const roomId = "your-room-id";
try {
// Initialize the SDK
const sdkInstance = await samvyo.JsSdk.init({
sessionToken,
roomId
});
// Listen for initialization success
sdkInstance.on('initSuccess', () => {
console.log("SDK initialized successfully");
});
// Handle initialization errors
sdkInstance.on('initError', (error) => {
console.error("Error initializing SDK:", error);
});
return sdkInstance;
} catch (error) {
console.error("Error in initialization process:", error);
throw error;
}
}
Note: You can use the same SDK instance for both joining rooms and processing files. There's no need to initialize the SDK multiple times if you're already using it for room functionality.
Processing Files
Once you have an initialized SDK instance, you can use the startProcessing
method to convert your MP4 files to HLS format.
Method Signature
startProcessing({
inputFiles: [{
type: "mp4",
url: "https://your-bucket.region.digitaloceanspaces.com/videos/input.mp4",
key: "videos/folder1/folder2" // optional
}],
outputQualities: ["360p", "720p", "1080p"], // optional
bucket: "your-bucket", // optional
region: "your-region" // optional
})
Input Parameters
inputFiles
: An array of objects containing:url
: The URL of the MP4 file in your Cloud storagetype
: The file type (currently only "mp4" is supported)key
: (Optional) The key/path where the processed file should be stored
outputQualities
: (Optional) An array of desired output qualities (up to 3)- Supported qualities: '2160p', '1440p', '1080p', '720p', '480p', '360p', '240p'
- If not specified, the system will use:
- Qualities configured in the dashboard settings (Settings > Recording Settings)
- If no dashboard settings, default to [720p, 360p]
bucket
: (Optional) Override the default bucket from dashboard settingsregion
: (Optional) Override the default region from dashboard settings
Example Usage
async function processFiles(sdkInstance) {
try {
// Example with all parameters
const result = await sdkInstance.startProcessing({
inputFiles: [
{
url: "https://your-bucket.region.digitaloceanspaces.com/videos/input1.mp4",
type: "mp4",
key: "videos/processed/input1"
}
],
outputQualities: ['1080p', '360p', '240p'],
bucket: "custom-bucket",
region: "custom-region"
});
// Example using default settings
const resultWithDefaults = await sdkInstance.startProcessing({
inputFiles: [
{
url: "https://your-bucket.region.digitaloceanspaces.com/videos/input2.mp4",
type: "mp4"
}
]
});
console.log("Processing started:", result);
} catch (error) {
console.error("Error processing files:", error);
}
}
// Example of processing multiple batches
async function processMultipleBatches(sdkInstance) {
const batchSize = 10;
const allFiles = [/* array of file objects */];
// Process files in batches of 10
for (let i = 0; i < allFiles.length; i += batchSize) {
const batch = allFiles.slice(i, i + batchSize);
await sdkInstance.startProcessing({
inputFiles: batch,
outputQualities: ['720p', '360p']
});
}
}
Output Files
After processing is complete, the output files will be stored in your Digital Ocean bucket. The processed files will include:
- An M3U8 playlist file
You will receive the output file details through the SDK's event system, which you can use to access the processed files.
Important Notes
- Storage Configuration: Ensure your storage settings are properly configured in the Samvyo dashboard before attempting file processing.
- File Access: The SDK needs proper access to your Digital Ocean storage to read input files and write output files.
- Quality Selection: Choose output qualities based on your target audience and their typical network conditions.
- Processing Time: The time required for processing depends on:
- Input file size
- Number of output qualities
- Server load
- Network conditions
Event Handling
The SDK provides several events to track the file processing status. You can listen to these events to handle the processing lifecycle:
// Listen for processing start
sdkInstance.on('processingStarted', (data) => {
console.log("Processing started:", data);
// data contains:
// - processingStartTime: Timestamp when processing started
// - requestId: Unique identifier for the processing request
});
// Listen for processing errors
sdkInstance.on('processingError', (error) => {
console.error("Error during file processing:", error);
// error contains:
// - processingError: The error that occurred
// - requestId: The request identifier
// - error details: Additional error information
});
// Listen for processing completion
sdkInstance.on('processingCompleted', (details) => {
console.log("Processing completed successfully:", details);
// details contains:
// - totalProcessingTime: Total time taken for processing in sec
// - hlsfileKey: Key of the generated HLS file
// - size: Size of the processed file in mb
// - originalFile: Information about the original input file
// - lastFile: Boolean indicating if this is the last file in the processing array
// - requestId: The request identifier
});
Example Usage with Event Handling
Here's a complete example showing how to handle all processing events:
async function processFilesWithEvents(sdkInstance) {
try {
// Set up event listeners before starting processing
sdkInstance.on('processingStarted', (data) => {
console.log("Processing started at:", new Date(data.processingStartTime));
console.log("Request ID:", data.requestId);
// Update UI to show processing status
updateProcessingStatus("Processing started...");
});
sdkInstance.on('processingError', (error) => {
console.error("Processing failed for request:", error.requestId);
console.error("Error details:", error.processingError);
// Update UI to show error
updateProcessingStatus("Processing failed: " + error.processingError);
});
sdkInstance.on('processingCompleted', (details) => {
console.log("Processing completed successfully");
console.log("Total processing time:", details.totalProcessingTime);
console.log("HLS file key:", details.hlsfileKey);
console.log("File size:", details.size);
console.log("Is last file:", details.lastFile);
// Update UI with processed file information
updateProcessingStatus("Processing completed!");
if (details.lastFile) {
console.log("All files have been processed");
}
});
// Start the processing
const result = await sdkInstance.startProcessing({
inputFiles: [
{
url: "https://your-bucket.region.digitaloceanspaces.com/videos/input1.mp4",
type: "mp4"
}
],
outputQualities: ['1080p', '360p', '240p']
});
} catch (error) {
console.error("Error initiating file processing:", error);
}
}
These events allow you to:
- Track when processing starts with the exact timestamp
- Monitor processing progress and completion
- Handle errors with detailed error information
- Know when all files in a batch have been processed
- Access processing metrics like total processing time and file size
Make sure to implement appropriate error handling and user feedback based on these events to provide a good user experience.
Summary
The file processing feature in the Samvyo SDK allows you to:
- Convert MP4 files to HLS format
- Generate multiple quality levels for adaptive streaming
- Store processed files in your Digital Ocean storage
- Access processed files through the provided output details
Make sure to properly configure your storage settings and handle the processing events to ensure smooth operation of the file processing feature.