Getting Started

This guide will enable you to quickly and easily get started with building your own video experiences and exploring the platform’s basic capabilities.

Before You Begin

You will need your Kaltura account credentials. If you don’t have them yet, start a free trial.
If you’ve signed in, you can click on your account info at the top right of this page to view your credentials.
You can also find them at any time in the KMC’s (Kaltura Management Console) by clicking the Integration Settings tab.

The simplest way to make requests to the Kaltura REST API is by using one of the Kaltura API Client Libraries. We don’t recommend making REST API requests directly, as your URL requests might get really long and tricky.

Once you’ve downloaded the client library, you’ll need to import the library and instantiate a KalturaClient object with which you’ll make calls to the API.
Setup looks like this:

from KalturaClient import *

config = KalturaConfiguration()
client = KalturaClient(config)

require_once('lib/KalturaClient.php');

$config = new KalturaConfiguration();
$client = new KalturaClient($config);

const kaltura = require('kaltura-client');
const config = new kaltura.Configuration();
const client = new kaltura.Client(config);

public static Client generateKalturaClient() {
        Configuration config = new Configuration();
        Client client = new Client(config);
        return client;
    }

The steps below will walk you through a few basic Kaltura APIs. If you’re looking for languages that are not available here, you can click on any of the actions mentioned to see them in our interactive console.

Kaltura Session

Because the Kaltura API is stateless, every request made to the API requires an authentication session to be passed along with the request. With the client library, it’s easy to set it once using the session.start API action, like this:

ks = client.session.start(
  <"ADMIN SECRET">,
  <"UNIQUE USER ID">,
  KalturaSessionType.ADMIN,
  <PARTNER ID>, 
  <EXPIRY>, 
  "appId:appName-appDomain") 
client.setKs(ks)

$ks = $client->session->start(
  <"ADMIN SECRET">,
  <"UNIQUE USER ID">,
  KalturaSessionType::ADMIN,
  <PARTNER ID>,
  <EXPIRY>,
  "appId:appName-appDomain");
$client->setKS($ks);

kaltura.services.session.start(
	<"ADMIN SECRET">,
	<"UNIQUE USER ID">,
	kaltura.enums.SessionType.ADMIN,
	<PARTNER ID>,
	<EXPIRY>,
	"appId:appName-appDomain")
.completion((success, ks) => {
	client.setKs(ks);
});

String session = client.getSessionService().start(
	<"ADMIN SECRET">, 
	<"UNIQUE USER ID">, 
	KalturaSessionType.ADMIN, 
	<PARTNER ID>, 
	<EXPIRY>, 
	"appId:appName-appDomain");

client.setSessionId(session);

Specifying an app id which contains the name and domain of the app allows you to get specific analytics per application, for cases where you’re running your application on various domains.

Try it interactively with this workflow.

Generating a KS with session.start is simple, and great for applications which you alone have access to.
Other methods include the user.loginByLoginId action, which allows users to log in using their own KMC credentials, and the appToken service, which is recommended when providing access to applications in production that are managed by others.
Learn more here about various ways to create a Kaltura Session.

Uploading Media Files

Kaltura is built to handle files of all types and size. To best handle the upload of large files, Kaltura’s upload API provides the ability to upload files in smaller chunks, in parallel (multiple chunks can be uploaded simultaneously to improve network utilization), as well as pause-and-resume and chunk upload retries in case of temporary network failures.

Step 1: Create an Upload Token

You’ll use uploadToken.add to create an uploadToken for your new video.

upload_token = KalturaUploadToken()
token = client.uploadToken.add(upload_token);

$uploadToken = new KalturaUploadToken();
$token = $client->uploadToken->add($uploadToken);

let uploadToken = new kaltura.objects.UploadToken();

kaltura.services.uploadToken.add(uploadToken)
.execute(client)
.then(token => {
    console.log(token);
});

UploadToken uploadToken = new UploadToken();

AddUploadTokenBuilder requestBuilder = UploadTokenService.add(uploadToken)
.setCompletion(new OnCompletion<Response<UploadToken>>() {
    @Override
    public void onComplete(Response<UploadToken> token) {
        System.out.println(token);
    }
});

An UploadToken is essentially a container that holds any file that will be uploaded to Kaltura. The token has an ID that is attached to the location of the file. This process allows the upload to happen independently of the entry creation. In the case of large files, for example, the same uploadToken ID is used for each chunk of the same file.

About Chunked File Uploading

How it works:

On the client side of the app, the file is chunked into multiple fragments (of adjustable size)
The chunks are then uploaded to Kaltura storage (in some cases simultaneously)
Once all the chunks have arrived, they are assembled to form the original file [on the server side] so that file processing can begin

Kaltura has three widgets that you can use for chunked uploading:

JS Library (supports parallel uploading)
Java Library (supports parallel uploading)
jQuery Library (for jQuery based applications)

To upload manually, continue following the steps:

Step 2: Upload the File Data

We’ll call uploadToken.upload to upload a new video file using the newly created token. If you don’t have a video file handy, you can right-click this link to save a sample video of Kaltura’s logo. In the case of large files, resume should be set to true and finalChunk is set to false until the final chunk. resumeAt determines at which byte to chunk the next fragment.

upload_token_id = token.id
file_data =  open('Kaltura_Logo_Animation.flv', 'r')
resume = False
final_chunk = True	
resume_at = 0
result = client.uploadToken.upload(upload_token_id, file_data, resume, final_chunk, resume_at)

$uploadTokenId = $token->id;
$fileData = "/path/to/file";
$resume = false;
$finalChunk = true;
$resumeAt = -1;

$result = $client->uploadToken->upload($uploadTokenId, $fileData, $resume, $finalChunk, $resumeAt);

let uploadToken = new kaltura.objects.UploadToken();

kaltura.services.uploadToken.add(uploadToken)
.execute(client)
.then(token => {
    let uploadTokenId = token.id;
	let fileData = '/path/to/file';
	let resume = false;
	let finalChunk = true;
	let resumeAt = -1;

	kaltura.services.uploadToken.upload(uploadTokenId, fileData, resume, finalChunk, resumeAt)
	.execute(client)
	.then(result => {
	    console.log(result);
	});
});

UploadToken uploadToken = new UploadToken();

AddUploadTokenBuilder requestBuilder = UploadTokenService.add(uploadToken)
.setCompletion(new OnCompletion<Response<UploadToken>>() {
    @Override
    public void onComplete(Response<UploadToken> token) {
        String uploadTokenId = token.id;
		File fileData = new FileInputStream("/path/to/file");
		boolean resume = false;
		boolean finalChunk = true;
		int resumeAt = -1;

		UploadUploadTokenBuilder requestBuilder = UploadTokenService.upload(uploadTokenId, fileData, resume, finalChunk, resumeAt)
	    .setCompletion(new OnCompletion<Response<UploadToken>>() {
	        @Override
	        public void onComplete(Response<UploadToken> result) {
	            System.out.println(result);
	        }
	    });
    }
});

Step 3: Creating the Kaltura Media Entry

Here’s where you’ll set your video’s name and description use media.add to create the entry.

media_entry = KalturaMediaEntry()
media_entry.name = "Kaltura Logo"
media_entry.description = "sample video of kaltura logo"
media_entry.mediaType = KalturaMediaType.VIDEO
entry = client.media.add(media_entry)

$mediaEntry = new KalturaMediaEntry();
$mediaEntry->name = "Kaltura Logo";
$mediaEntry->description = "sample video of kaltura logo";
$mediaEntry->mediaType = KalturaMediaType::VIDEO;

$entry = $client->media->add($mediaEntry);

let uploadToken = new kaltura.objects.UploadToken();

kaltura.services.uploadToken.add(uploadToken)
.execute(client)
.then(token => {
    let uploadTokenId = token.id;
	let fileData = '/path/to/file';
	let resume = false;
	let finalChunk = true;
	let resumeAt = -1;

	kaltura.services.uploadToken.upload(uploadTokenId, fileData, resume, finalChunk, resumeAt)
	.execute(client)
	.then(result => {
	    let mediaEntry = new kaltura.objects.MediaEntry();
		mediaEntry.name = "Kaltura Logo";
		mediaEntry.description = "sample video of kaltura logo";
		mediaEntry.mediaType = kaltura.enums.MediaType.VIDEO;

		kaltura.services.media.add(mediaEntry)
		.execute(client)
		.then(entry => {
		    console.log(entry);
		});
	});
});

UploadToken uploadToken = new UploadToken();

AddUploadTokenBuilder requestBuilder = UploadTokenService.add(uploadToken)
.setCompletion(new OnCompletion<Response<UploadToken>>() {
    @Override
    public void onComplete(Response<UploadToken> token) {
        String uploadTokenId = token.id;
		File fileData = new FileInputStream("/path/to/file");
		boolean resume = false;
		boolean finalChunk = true;
		int resumeAt = -1;

		UploadUploadTokenBuilder requestBuilder = UploadTokenService.upload(uploadTokenId, fileData, resume, finalChunk, resumeAt)
	    .setCompletion(new OnCompletion<Response<UploadToken>>() {
	        @Override
	        public void onComplete(Response<UploadToken> result) {
	            MediaEntry mediaEntry = new MediaEntry();
	            AddMediaBuilder requestBuilder = MediaService.add(mediaEntry)
    			.setCompletion(new OnCompletion<Response<MediaEntry>>() {
	        		@Override
	        		public void onComplete(Response<MediaEntry> entry) {
	            		System.out.println(entry);
	        		}
    			});
    		}
	    });
    }
});

The Kaltura Entry is a logical object that package all of the related assets to the uploaded file. The Media Entry represents Media assets (such as Image, Audio, or Video assets) and references all of the metadata, caption assets, transcoded renditions (flavors), thumbnails, access control rules, entitled users or any other related asset that is a part of that particular media item.

Step 4: Attach the Video

Now that you have your entry, you need to associate it with the uploaded video token using media.addContent.

entry_id = entry.id
resource = KalturaUploadedFileTokenResource()
resource.token = upload_token_id

result = client.media.addContent(entry_id, resource)

$entryId = $entry->id;
$resource = new KalturaUploadedFileTokenResource();
$resource->token = $uploadTokenId;

$result = $client->media->addContent($entryId, $resource);

let uploadToken = new kaltura.objects.UploadToken();

kaltura.services.uploadToken.add(uploadToken)
.execute(client)
.then(token => {
    let uploadTokenId = token.id;
	let fileData = '/path/to/file';
	let resume = false;
	let finalChunk = true;
	let resumeAt = -1;

	kaltura.services.uploadToken.upload(uploadTokenId, fileData, resume, finalChunk, resumeAt)
	.execute(client)
	.then(result => {
	    let mediaEntry = new kaltura.objects.MediaEntry();
		mediaEntry.name = "Kaltura Logo";
		mediaEntry.description = "sample video of kaltura logo";
		mediaEntry.mediaType = kaltura.enums.MediaType.VIDEO;

		kaltura.services.media.add(mediaEntry)
		.execute(client)
		.then(entry => {
		    let entryId = entry.id
			let resource = new kaltura.objects.UploadedFileTokenResource();
			resource.token = uploadTokenId;

			kaltura.services.media.addContent(entryId, resource)
			.execute(client)
			.then(result => {
			    console.log(result);
			});
		});
	});
});

UploadToken uploadToken = new UploadToken();

AddUploadTokenBuilder requestBuilder = UploadTokenService.add(uploadToken)
.setCompletion(new OnCompletion<Response<UploadToken>>() {
    @Override
    public void onComplete(Response<UploadToken> token) {
        String uploadTokenId = token.id;
		File fileData = new FileInputStream("/path/to/file");
		boolean resume = false;
		boolean finalChunk = true;
		int resumeAt = -1;

		UploadUploadTokenBuilder requestBuilder = UploadTokenService.upload(uploadTokenId, fileData, resume, finalChunk, resumeAt)
	    .setCompletion(new OnCompletion<Response<UploadToken>>() {
	        @Override
	        public void onComplete(Response<UploadToken> result) {
	            MediaEntry mediaEntry = new MediaEntry();
	            AddMediaBuilder requestBuilder = MediaService.add(mediaEntry)
			    .setCompletion(new OnCompletion<Response<MediaEntry>>() {
			        @Override
			        public void onComplete(Response<MediaEntry> entry) {
			            String entryId = entry.id;
						UploadedFileTokenResource resource = new UploadedFileTokenResource();

						AddContentMediaBuilder requestBuilder = MediaService.addContent(entryId, resource)
    					.setCompletion(new OnCompletion<Response<MediaEntry>>() {
					        @Override
					        public void onComplete(Response<MediaEntry> result) {
					            System.out.println(result);
					        }
    					});
        			}
    			});
        	}
    	});
    }
});

At this point, Kaltura will start analyzing the uploaded file, prepare for the transcoding and distribution flows and any other predefined workflows or notifications.

Finding Entries

To retrieve that newly uploaded entry, we’ll use media.list. If you inspect that API in the console, and expand the filter object, you’ll see a whole bunch of options for filtering down to the entries you want.

Finding Entries By Name

In the case of this example, a quick way to find the new entry is by searching for part of its name - in this case, “Logo”. We need a filter object called KalturaMediaEntryFilter on which to set the values, which we then pass to the endpoint.

filter = KalturaMediaEntryFilter()
filter.nameLike = "Logo"
pager = KalturaFilterPager()

result = client.media.list(filter, pager)
print(result)

$filter = new KalturaMediaEntryFilter();
$filter->nameLike = "Logo";
$pager = new KalturaFilterPager();

$result = $client->media->listAction($filter, $pager);

let filter = new kaltura.objects.MediaEntryFilter();
filter.nameLike = "Logo";
let pager = new kaltura.objects.FilterPager();

kaltura.services.media.listAction(filter, pager)
.execute(client)
.then(result => {
    console.log(result);
});

MediaEntryFilter filter = new MediaEntryFilter();
filter.setNameLike("Logo");
FilterPager pager = new FilterPager();

ListMediaBuilder requestBuilder = MediaService.list(filter, pager)
    .setCompletion(new OnCompletion<Response<ListResponse<MediaEntry>>>() {
        @Override
        public void onComplete(Response<ListResponse<MediaEntry>> result) {
            System.out.println(result);
        }
    });

The result will return as a list of KalturaMediaEntry objects. Notice the Pager object. It is useful for large result sets if you want to get a specific amount of results for page.

Finding Entries By Date

Another way to find the entry is by date. Using epoch timestamp, this code lists all entries created in July of 2019:

filter = KalturaMediaEntryFilter()
filter.createdAtGreaterThanOrEqual = 1561982373
filter.createdAtLessThanOrEqual = 1564660773
pager = KalturaFilterPager()

result = client.media.list(filter, pager)


$filter = new KalturaMediaEntryFilter();
$filter->createdAtGreaterThanOrEqual = 1561982373;
$filter->createdAtLessThanOrEqual = 1564660773;
$pager = new KalturaFilterPager();

$result = $client->media->listAction($filter, $pager);

let filter = new kaltura.objects.MediaEntryFilter();
filter.createdAtGreaterThanOrEqual = 1561982373;
filter.createdAtLessThanOrEqual = 1564660773;
let pager = new kaltura.objects.FilterPager();

kaltura.services.media.listAction(filter, pager)
.execute(client)
.then(result => {
    console.log(result);
});

MediaEntryFilter filter = new MediaEntryFilter();
filter.setCreatedAtGreaterThanOrEqual(1561982373);
filter.setCreatedAtLessThanOrEqual(1564660773);
FilterPager pager = new FilterPager();

ListMediaBuilder requestBuilder = MediaService.list(filter, pager)
    .setCompletion(new OnCompletion<Response<ListResponse<MediaEntry>>>() {
        @Override
        public void onComplete(Response<ListResponse<MediaEntry>> result) {
            System.out.println(result);
        }
    });

Note that Kaltura Sessions with limited privileges might get limited results when making a media.list API call.

To conduct a more thorough search, for example, if you want to search within captions or metadata, use the Kaltura Search API. Read about it here.

Embedding Your Video Player

You have your entry ID, so you’re just about ready to embed the kaltura player, but first you’ll need a UI Conf ID, which is basically the ID of the player in which the video is shown.
For this you’ll need to log into the KMC and click on the Studio tab.

Notice that there are two studio options: TV and Universal.
The Universal player (or mwEmbed as we call it) offers legacy support - such as for enterprise customers using the old internet explorer - and also features interactivity options, like the dual player or In-Video Quizzes.
The TV player (or playkit) is built on modern javascript and focuses more on performance. Both players are totally responsive.

We will focus on the TV player, for which you can find resources and information here.

Create a new TV player, give it a name, and check out the various player options.
Save the player and go back to players list; you should now see it the top of the player list. Notice that player ID - that is your UI Conf ID.
Now you can use it for embedding your player:

Dynamic Player Embed

The first script in the code below loads the player, and the second script handles the embed. This method of embedding makes it easy to dynamically control the configuration of the player during runtime.

<div id="{TARGET_ID}" style="width: 640px;height: 360px"></div>
<script type="text/javascript" src="https://cdnapisec.kaltura.com/p/{PARTNER_ID}/embedPlaykitJs/uiconf_id/{UICONF_ID}"></script>
  <script type="text/javascript">
    try {
      var kalturaPlayer = KalturaPlayer.setup({
        targetId: "{TARGET_ID}",
        provider: {
          partnerId: {PARTNER_ID},
          uiConfId: {UICONF_ID}
        },
        playback: {
          autoplay: true
          }
      });
      kalturaPlayer.loadMedia({entryId: '{ENTRY_ID}'});
    } catch (e) {
      console.error(e.message)
    }
  </script>

Learn about other embed types here.

Wrapping Up

Including a Kaltura Session allows you to keep track of user analytics for each entry and set permissions and privileges. Notice that in this case, the KS is created on the server side of the app.

Congrats! You’ve learned how to:

Create a kaltura session
Upload media to your Kaltura account
Search for your media
Show your media in a Kaltura Player

Next steps:

Read the eSearch blog post
Learn how to create and handle thumbnails
Analyze Engagement Analytics

You can find more API resources in our docs, play around in the console, or enjoy full interactive experiences with our workflows.

And of course, feel free to reach out at vpaas@kaltura.com if you have any questions.

Admin

Resources

From our blog

Navigation

Get Started with Kaltura VPaaS

Getting Started

Before You Begin

Kaltura Session

Uploading Media Files

About Chunked File Uploading

Finding Entries

Finding Entries By Name

Finding Entries By Date

Embedding Your Video Player

Dynamic Player Embed

Wrapping Up

VPaaS

Tools

Resources

Community

Open Source

Admin

Resources

From our blog

API Authorization

Navigation

Kaltura API DocumentationGet Started with the Kaltura API

Getting Started

Before You Begin

Kaltura Session

Uploading Media Files

About Chunked File Uploading

Finding Entries

Finding Entries By Name

Finding Entries By Date

Embedding Your Video Player

Dynamic Player Embed

Wrapping Up

VPaaS

Tools

Resources

Community

Open Source