VideoThumbnailer Class

Generates meaningful thumbnails for a video.

Definition

Namespace: GleamTech.VideoUltimate
Assembly: GleamTech.VideoUltimate (in GleamTech.VideoUltimate.dll) Version: 3.8.7
C#
public class VideoThumbnailer : IDisposable
Inheritance
Object    VideoThumbnailer
Implements
IDisposable

Example

C#
//Read video from "c:\SomeFolder\InputFile.mp4"
using (var videoThumbnailer = new VideoThumbnailer(@"c:\SomeFolder\InputFile.mp4"))
{
}

//---------------------------------------

//Read with a virtual path string:
//See below for other path string examples.
using (var videoThumbnailer = new VideoThumbnailer("~/SomeFolder/InputFile.mp4"))
{
}

//Read with a URL string:
//See below for other path string examples.
using (var videoThumbnailer = new VideoThumbnailer("http://example.com/SomeFolder/InputFile.mp4"))
{
}

//Read with a Data URL string:
//See below for other path string examples.
using (var videoThumbnailer = new VideoThumbnailer("data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"))
{
}

//Read with a file provider instance:
//See below for other file provider examples (UNC Path, AmazonS3, AzureBlob, Database etc.).
var fileProvider = new FileSystemFileProvider
{
    File = "InputFile.mp4",
    Location = new PhysicalLocation
    {
        Path = @"c:\SomeFolder"
    }
};
using (var videoThumbnailer = new VideoThumbnailer(fileProvider))
{
}

//Read with a provider string:
//See below for other provider string examples (UNC Path, AmazonS3, AzureBlob, Database etc.).
using (var videoThumbnailer = new VideoThumbnailer(@"Type=FileSystem; File=InputFile.mp4; Location='Type=Physical; Path=c:\SomeFolder'"))
{
}

Get the thumbnail of a video file and save it as an image file:

C#
using (var videoThumbnailer = new VideoThumbnailer(@"C:\Video.mp4"))
//Generate a meaningful thumbnail of the video and
//get a System.Drawing.Bitmap with 100x100 maximum size.
//You are responsible for disposing the bitmap when you are finished with it.
//So it's good practice to have a "using" statement for the retrieved bitmap.
using (var thumbnail = videoThumbnailer.GenerateThumbnail(100))
    //Reference System.Drawing and use System.Drawing.Imaging namespace for the following line.
    thumbnail.Save(@"C:\Thumbnail1.jpg", ImageFormat.Jpg);

Get the thumbnail of a video file from a stream:

C#
using (Stream videoStream = OpenYourVideoStream())
using (var videoThumbnailer = new VideoThumbnailer(videoStream))
{
    //Process..
}

Get the thumbnail of a video file from a URL:

C#
using (var videoThumbnailer = new VideoThumbnailer(@"C:\Video.mp4"))
{
    //Get the thumbnail with 100x100 maximum size and overlay video duration 
    //on the bottom-right of the thumbnail (like youtube does).
    using (var thumbnail = videoThumbnailer.GenerateThumbnail(100, true))
        thumbnail.Save(@"C:\Thumbnail100WithDuration.jpg", ImageFormat.Jpg);

    //Get the same thumbnail this time with 300x300 maximum size.
    //Thumbnail frame is already generated on the first call above so you can
    //get different sizes of the thumbnail many times very fast
    using (var thumbnail = videoThumbnailer.GenerateThumbnail(300))
        thumbnail.Save(@"C:\Thumbnail300WithoutDuration.jpg", ImageFormat.Jpg);
}

  Notes to Callers

Below are the examples for setting a FileProvider parameter/property.

Setting a plain string:

C#
FileProvider fileProvider;

//Setting a physical/virtual path string:
//These strings are parsed as a FileSystemFileProvider instance with a PhysicalLocation instance.
fileProvider = @"c:\SomeFolder\SomeFile.ext";
//Note that virtual paths can only be resolved in a web application
//and on Linux paths starting with "/" are physical paths and not virtual paths.
fileProvider = "/SomeFolder/SomeFile.ext";
fileProvider = "~/SomeFolder/SomeFile.ext"; //"~" means relative to web application root.

//Setting a URL or a Data URL string:
//Strings starting with "http://" or "https://" are parsed as a UrlFileProvider instance.
//Strings starting with "data:" are parsed as a DataUrlFileProvider instance.
fileProvider = "http://example.com/SomeFolder/SomeFile.ext";
fileProvider = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

Setting a MemoryFileProvider instance, to connect to a file in a byte array (byte) or a MemoryStream:

C#
FileProvider fileProvider;

//Setting a MemoryFileProvider instance,
//to connect to a file in a byte array (byte[]) or a MemoryStream:
//Optional parameter dateModified: used for detailed file info, e.g. for generating better cache keys.
fileProvider = new MemoryFileProvider(
    "SomeFile.ext", //file can also be set as a relative path "SomeFolder/SomeFile.ext".
    yourByteArray,
    yourFileDateModified //Provide dateModified to prevent cache key conflicts.
);
fileProvider = new MemoryFileProvider(
    "SomeFile.ext", //file can also be set as a relative path "SomeFolder/SomeFile.ext".
    yourMemoryStream,
    yourFileDateModified //Provide dateModified to prevent cache key conflicts.
);

//Create with empty MemoryStream
//Note that this instance should be written (filled with data via OpenWrite method) before being read
fileProvider = new MemoryFileProvider("SomeFolder/SomeFile.ext");

Setting a StreamFileProvider instance, to connect to a file in a Stream:

C#
FileProvider fileProvider;

//Setting a StreamFileProvider instance,
//to connect to a file in a Stream:
//Optional parameters dateModified and size: used for detailed file info, e.g. for generating better cache keys.
fileProvider = new StreamFileProvider(
    "SomeFile.ext", //file can also be set as a relative path "SomeFolder/SomeFile.ext".
    yourStream,
    yourFileDateModified, //Provide dateModified to prevent cache key conflicts.
    yourFileSize //Provide size only if your stream is not seekable to prevent cache key conflicts.
);

Setting a FileSystemFileProvider instance with a PhysicalLocation instance, to connect to physical file system:

C#
FileProvider fileProvider;

//Setting a physical file provider via a FileSystemFileProvider instance:
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        //Path can also be virtual path string like "~/SomeFolder" in a web application.
        Path = @"c:\SomeFolder"
    }
};

//Setting a physical file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=Physical; Path=c:\SomeFolder'";

//---------------------------------------

//Setting a FileSystemFileProvider instance with a PhysicalLocation instance,
//to connect as a specific Windows user to a UNC path or a protected local path:
//UserName can be specified as "Domain\User", "User@Domain" (UPN format), "Machine\User", "User" (local user).
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        Path = @"\\server\share", //Path can be a UNC path or a local path
        UserName = "USERNAME",
        Password = "PASSWORD"
    }
};

//Setting a physical file provider via a provider string, to connect as a specific user (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Path=\\server\share; User Name=USERNAME; Password=PASSWORD'";

//---------------------------------------

//Setting a physical file provider via a FileSystemFileProvider instance, to connect as the authenticated user:
//If Windows Authentication is used in IIS for this site, location can be specified like this
//to connect as the already authenticated user: 
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        Path = @"\\server\share", //Path can be a UNC path or a local path
        AuthenticatedUser = AuthenticatedUser.Windows
    }
};

//Setting a physical file provider via a provider string, to connect as the authenticated user:
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Path=\\server\share; Authenticated User=Windows'";

Setting a FileSystemFileProvider instance with an AzureBlobLocation instance, to connect to Azure Blob cloud file system:

C#
FileProvider fileProvider;

//Setting a FileSystemFileProvider instance with an AzureBlobLocation instance,
//to connect to Azure Blob cloud file system.
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new AzureBlobLocation
    {
        //Leave Path empty to connect to the root of the container. 
        //For connecting to subfolders, Path should be specified as a relative path (eg. "some/folder")
        //Path = "some/folder",

        //Get these values from your Azure Portal (Storage Account -> Access Keys -> Connection String)
        Container = "CONTAINER",
        AccountName = "XXX",
        AccountKey = "XXX"
    }
};

//Setting a an Azure Blob file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=AzureBlob; Container=CONTAINER; Account Name=XXX; Account Key=XXX'";

Setting a FileSystemFileProvider instance with an AmazonS3Location instance, to connect to Amazon S3 cloud file system:

C#
FileProvider fileProvider;

//Setting a FileSystemFileProvider instance with an AmazonS3Location instance,
//to connect to Amazon S3 cloud file system.
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new AmazonS3Location
    {
        //Leave Path empty to connect to the root of the bucket. 
        //For connecting to subfolders, Path should be specified as a relative path (eg. "some/folder")
        //Path = "some/folder",

        BucketName = "BUCKET",
        Region = "eu-central-1",
        AccessKeyId = "XXX",
        SecretAccessKey = "XXX",
    }
};

//Setting an Amazon S3 file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=AmazonS3; Bucket Name=BUCKET; Region=eu-central-1; Access Key Id=XXX; Secret Access Key=XXX'";

Setting a UrlFileProvider instance, to connect to a file located at a URL:

C#
FileProvider fileProvider;

//Setting a URL file provider via a UrlFileProvider instance:
//File should start with "http://" or "https://".
fileProvider = new UrlFileProvider
{
    File = "http://example.com/SomeFolder/SomeFile.ext"
};

//Setting a URL file provider via a provider string (same as above):
fileProvider = "Type=Url; File=http://example.com/SomeFolder/SomeFile.ext";

Setting a DataUrlFileProvider instance, to connect to a file encoded in a Data URL:

C#
FileProvider fileProvider;

//Setting a Data URL file provider via a UrlFileProvider instance:
//File should start with "data:".
fileProvider = new DataUrlFileProvider
{
    File = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
};

//Setting a Data URL file provider via a provider string (same as above):
fileProvider = "Type=DataUrl; File='data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'";

Setting a DatabaseFileProvider instance, to connect to a database file system:

C#
FileProvider fileProvider;

//Setting a DatabaseFileProvider instance,
//to connect to a database file system.
fileProvider = new DatabaseFileProvider
{
    File = "SomeFile.ext", //File can also be set as a relative path "SomeFolder/SomeFile.ext".
    ConnectionString = "Data Source=(local); Initial Catalog=SomeDb; Integrated Security=SSPI",
    //ProviderName = "System.Data.SqlClient" //ProviderName default value is "System.Data.SqlClient"

    Table = "SomeTable", //Table default value is "File".

    //Mandatory fields:
    KeyField = "Path", //KeyField default value is "Id".
    ContentField = "Content", //ContentField default value is "Content".

    //Optional fields DateModifiedField and SizeField: used for detailed file info, e.g. for generating better cache keys.
    //NameField = "Name", //NameField used for overriding file name specified in File.
    DateModifiedField = "DateModified", //Provide DateModifiedField to prevent cache key conflicts.
    SizeField = "Size" //Provide SizeField to prevent cache key conflicts.
};

//Setting a database file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = "Type=Database; File=SomeFolder/SomeFile.ext; Connection String='Data Source=(local); Initial Catalog=SomeDb; Integrated Security=SSPI'; Table=SomeTable; Key Field=Path; Content Field=Content";

//---------------------------------------

/*

Sample SQL script to create a table in the database:

CREATE TABLE [File] (
    [Id] [int] IDENTITY(1, 1) PRIMARY KEY,
    [Path] [nvarchar](500) NOT NULL UNIQUE,
    [Name] [nvarchar](100),
    [DateModified] [smalldatetime],
    [Size] [bigint],
    [Content] [varbinary](max)
);

*
*/

Setting a AssemblyResourceFileProvider instance, to connect to a file embedded in an assembly:

C#
FileProvider fileProvider;

//Setting an assembly resource file provider via a AssemblyResourceFileProvider instance:
fileProvider = new AssemblyResourceFileProvider
{
    File = @"SomeFolder\SomeFile.ext",
    Assembly = typeof(SomeType).Assembly,
    BaseNamespace = typeof(SomeType).Namespace
};

//Setting an assembly file provider via a provider string (same as above):
fileProvider = @"Type=AssemblyResource; File=SomeFolder\SomeFile.ext; Assembly=SomeAssembly; Base Namespace=Some.Namespace";

Setting a TemporaryFileProvider instance, to connect to a temporary file:

C#
FileProvider fileProvider;

//Setting a temporary file provider via a TemporaryFileProvider instance:
//Note that this instance should be written (filled with data via OpenWrite method) before being read
fileProvider = new TemporaryFileProvider("SomeFolder/SomeFile.ext");

Setting and implementing a custom file provider:

C#
FileProvider fileProvider;

//Setting a custom file provider:
fileProvider = new CustomFileProvider
{
    File = @"SomeFolder\SomeFile.ext",
    Parameters = new Dictionary<string, string>
    {
        {"parameter1", "value1"}
    }
};
C#
public class CustomFileProvider: FileProvider
{
    public override string File { get; set; }

    //Return true if DoGetInfo method is implemented, and false if not.
    public override bool CanGetInfo => true;

    //Return true if DoOpenRead method is implemented, and false if not.
    public override bool CanOpenRead => true;

    //Return true if DoOpenWrite method is implemented, and false if not.
    public override bool CanOpenWrite => false;

    //Return true only if File identifier is usable across processes/machines.
    public override bool CanSerialize => false;

    protected override FileProviderInfo DoGetInfo()
    {
        //Return info here which corresponds to the identifier in File property.

        //When this file provider is used in DocumentViewer:
        //This method will be called every time DocumentViewer requests a document.
        //The cache key and document format will be determined according to the info you return here.

        string fileName = File;
        DateTime dateModified = DateTime.Now;
        long size = 81920;

        return new FileProviderInfo(fileName, dateModified, size);

        //throw new NotImplementedException();
    }

    protected override Stream DoOpenRead()
    {
        //Open and return a readable stream here which corresponds to the identifier in File property.

        //You can make use of Parameters dictionary which was passed when this provider was initialized.
        //var someParameter = Parameters["parameter1"];

        //When this file provider is used in DocumentViewer:
        //This method will be called only when original input document is required, 
        //For example if DocumentViewer already did the required conversions and cached the results, 
        //it will not be called.

        return readableStream;

        //throw new NotImplementedException();
    }

    protected override Stream DoOpenWrite()
    {
        //Open and return a writable stream here which corresponds to the identifier in File property.

        throw new NotImplementedException();
    }
}

Constructors

VideoThumbnailer(FileProvider, VideoUltimateConfiguration) Initializes a new instance of the VideoThumbnailer class from the specified video file.
VideoThumbnailer(Stream, VideoUltimateConfiguration) Initializes a new instance of the VideoThumbnailer class from the specified video stream.

Methods

DisposeReleases all resources used by this instance.
GenerateThumbnail(Int32, Boolean, Int32) Generates a meaningful thumbnail for the video by seeking to a sensible time position and avoiding blank frames. Every call returns a new Image instance which should be disposed by the caller. Once the smart time position is determined after the first call, the consecutive calls will be faster and can be used to retrieve Image instances in different sizes.
GenerateThumbnail(Int32, Int32, Boolean, Int32) Generates a meaningful thumbnail for the video by seeking to a sensible time position and avoiding blank frames. Every call returns a new Image instance which should be disposed by the caller. Once the smart time position is determined after the first call, the consecutive calls will be faster and can be used to retrieve Image instances in different sizes.

See Also