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:

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.

Searching Entries

To retrieve that newly uploaded entry, we’ll use the Kaltura Search API.

Step 1: Params and Operator
If you have multiple search conditions, you would set an AND or OR to your operator, but in this case we’ll only be searching for one item. However, you still need to add a searchItems array to the operator.

searchParams = KalturaESearchEntryParams()
searchParams.searchOperator = KalturaESearchEntryOperator()
searchParams.searchOperator.searchItems = []
$elasticSearchPlugin = KalturaElasticSearchClientPlugin::get($client);
$searchParams = new KalturaESearchEntryParams();
$searchParams->searchOperator = new KalturaESearchEntryOperator();
$searchParams->searchOperator->searchItems = [];
let searchParams = new kaltura.objects.ESearchEntryParams();
searchParams.searchOperator = new kaltura.objects.ESearchEntryOperator();
searchParams.searchOperator.searchItems = [];
ESearchEntryParams searchParams = new ESearchEntryParams();
searchParams.setSearchOperator(new ESearchEntryOperator());
searchParams.getSearchOperator().setSearchItems(new ArrayList<ESearchEntryBaseItem>(1));

 

Step 2: Search Type

We’ll be using the Unified search, which searches through all entry data, such as metadata and captions. Other options are KalturaESearchEntryMetadataItem or KalturaESearchEntryCuePointItem. We’ll add that search item to the first index of the search operator.

searchParams.searchOperator.searchItems[0] = KalturaESearchUnifiedItem()
$searchParams->searchOperator->searchItems[0] = new KalturaESearchUnifiedItem();
searchParams.searchOperator.searchItems[0] = new kaltura.objects.ESearchUnifiedItem();
searchParams.getSearchOperator().getSearchItems().set(0, new ESearchUnifiedItem());

 

Step 3: Search Term

We’ll search for the kaltura logo sample video, which we named accordingly.

searchParams.searchOperator.searchItems[0].searchTerm = "kaltura logo"
$searchParams->searchOperator->searchItems[0]->searchTerm = "kaltura logo";
searchParams.searchOperator.searchItems[0].searchTerm = "kaltura logo";
searchParams.getSearchOperator().getSearchItems().get(0).setSearchTerm("kaltura logo");

 

Step 4: Search Item Type

In this case, we want an exact match of the text in our search term. Other options are partial or startsWith.

searchParams.searchOperator.searchItems[0].itemType = KalturaESearchItemType.EXACT_MATCH
$searchParams->searchOperator->searchItems[0]->itemType = KalturaESearchItemType::EXACT_MATCH;
searchParams.searchOperator.searchItems[0].itemType = kaltura.enums.ESearchItemType.EXACT_MATCH;
searchParams.getSearchOperator().getSearchItems().get(0).setItemType(ESearchItemType.EXACT_MATCH.getValue());

 

Step 5: Add Highlight

We set addHighlight to True so that we can see exactly where our search term appeared in the search results.

searchParams.searchOperator.searchItems[0].addHighlight = True
$searchParams->searchOperator->searchItems[0]->addHighlight = true;
searchParams.searchOperator.searchItems[0].addHighlight = true;
searchParams.getSearchOperator().getSearchItems().get(0).setAddHighlight(true);

 

Step 6: Search

result = client.elasticsearch.eSearch.searchEntry(searchParams);
print(result);
$result = $elasticSearchPlugin->eSearch->searchEntry($searchParams);
kaltura.services.eSearch.searchEntry(searchParams)
.execute(client)
.then(result => {
    console.log(result);
});
SearchEntryESearchBuilder requestBuilder = ESearchService.searchEntry(searchParams)
    .setCompletion(new OnCompletion<Response<ESearchEntryResponse>>() {
        @Override
        public void onComplete(Response<ESearchEntryResponse> result) {
            System.out.println(result);
        }
    });

 

Success! The result will return as a list of KalturaMediaEntry objects.

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:

  1. Create a new TV player, give it a name, and check out the various player options.
  2. 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

<script type="text/javascript">
		var kalturaPlayer = KalturaPlayer.setup({
			targetId: "kalturaplayer",
			provider: {
				partnerId: PARTER_ID,
				uiConfId: UI_CONF_ID
			},
			playback: {
				autoplay: true
			}
		});
		var mediaInfo = {
			entryId: ENTRY_ID,
			ks: KS
		};
		kalturaPlayer.loadMedia(mediaInfo);
	</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:

You can learn more about these steps 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.