Skip to main content

Encode and Register Videos

Overview​

Welcome to the how-to guide that walks you through the programmatic options on how to create and register new videos in the Axinom Video Service. In this guide, we will show you the essential steps and techniques to harness the power of GraphQL and the message bus for enoding and registering videos efficiently within our platform.

Our Video Service offers versatile ways to register and encode videos, and you can accomplish these tasks using GraphQL mutations and message bus commands. Whether you are a developer looking to integrate video processing into your application or an administrator importing existing encoded videos, this guide will provide you with clear instructions and best practices.

The service distinguishes two types of video flows: one where you have videos that need to be encoded into CMAF, HLS, and/or DASH first. You can use the Axinom Encoding Service to encode them. The other alternative is to register already encoded videos or videos from a third-party encoding pipeline. The following sections will guide you through the different options.

Encode Videos​

In this section, we will explore the process of initiating video encoding within our platform. Video encoding is a critical step in preparing videos for streaming, playback, or distribution. Whether you are encoding videos for the first time or optimizing your existing workflow, understanding how to start the encoding process is essential.

We will cover two primary methods for starting video encoding: using a GraphQL mutation and leveraging the message bus for encoding commands. These methods provide the flexibility to tailor your video processing workflow to your specific needs.

As a prerequisite to encode videos you need to define settings on how to acquire the source video, how it should be processed, the publish location, and DRM protection settings. These settings are described on this page:
Set up Encoding Profiles.

To utilize the API or dispatch a message, you will need to obtain a JWT (JSON Web Token) from the Identity Service. Detailed steps for obtaining this JWT can be found in the guide on Authenticate a service account.

Encode Videos via GraphQL​

All Mosaic Services provide a GraphQL API for data querying and mutation. Accessing the Video Service API is simple, and you can do so via a web browser at https://video.service.eu.axinom.net/graphiql. The actual GraphQL endpoint can be found at https://video.service.eu.axinom.net/graphql.

To initiate the encoding process, you will need to choose from your configured processing profiles. To retrieve the database ID of the 'DEFAULT' processing profile, you can use the following query:"

GraphQL query to get a profile
query DefaultProfile {
  encodingProcessingProfiles(condition: {title: "DEFAULT"}) {
    nodes {
      id
      title
      drmProtection
      outputFormat
      videoFormat
    }
  }
}

To start the encoding process you can use the encodeVideo mutation:

GraphQL mutation to encode video
mutation StartEncoding {
  encodeVideo(
    input: {
      videoRelativePath: "big-buck-bunny-folder", 
      processingProfileId: "d849dbd6-c438-4a2f-abfd-2a239e58a3e5"}
  ) {
    video {
      id
      title
      sourceLocation
    }
  }
}

This mutation performs a check to determine if a video corresponding to the provided source location already exists within the Video Service. If such a video does not exist, it initiates the encoding process through the Axinom Encoding Service. The progress of encoding, as well as a comprehensive encoding history, will be preserved for the newly generated video.

Encode Videos via Messaging​

An additional option, apart from utilizing the GraphQL API, involves dispatching an EnsureVideoExistsCommand through the Message Bus. This message incorporates required information such as the source location of the video requiring encoding, the title of the designated profile for video processing, and the optional inclusion of tags to associate with the video. This command will check if the video from the given source location was already encoded before. If this is not the case, it triggers the encoding procedure within the Axinom Encoding Service.

Sending the EnsureVideoExistsCommand
import {
  MessagingBrokerSettings,
  setupMessagingBroker,
} from '@axinom/mosaic-message-bus';
import {
  EnsureVideoExistsCommand,
  VideoServiceMultiTenantMessagingSettings,
} from '@axinom/mosaic-messages';
import { Config } from '../common';

(async () => {
  // Initialize the message broker with the correct settings
  const { tenantId, environmentId } = {} as Config;
  const brokerSettings = {} as MessagingBrokerSettings;
  const broker = await setupMessagingBroker(brokerSettings);

  // Acquire an auth token from the Identity Service
  const authToken = 'abc123';

  // Create the relevant payload to encode a video
  const messagePayload: EnsureVideoExistsCommand = {
    video_location: 'big-buck-bunny-folder',
    video_profile: 'DEFAULT',
    tags: ['MAIN', 'ANIMATED'],
  };

  // Publish the command message to start the encoding
  const { messageType, getEnvironmentRoutingKey } =
    VideoServiceMultiTenantMessagingSettings.EnsureVideoExists;
  await broker.publish(
    messageType,
    messagePayload,
    {
      auth_token: authToken,
    },
    {
      routingKey: getEnvironmentRoutingKey({
        tenantId,
        environmentId,
      }),
    },
  );
})();

As a follow-up, the service dispatches the following events, to which you can subscribe within your integration:

  • EnsureVideoExistsAlreadyExisted - this event is sent when there is already a video in the Video Service for the given source video location.
  • EnsureVideoExistsCreationStarted - this event is sent if a new video encoding was started for the given source video location.
  • EnsureVideoExistsFailed - this event is sent when something went wrong and the video encoding could not be started.
  • VideoEncodingFinished - this event is sent after the video encoding was successfully finished and it was stored in the publish location.
  • VideoEncodingFailed - this event is sent if the encoding process started but could not finish due to an error.

See the Messaging How-to guide on how to subscribe to events.

Register Custom Videos​

If you have already encoded videos or prefer to employ a third-party video encoder, you have the option to directly register these videos within the Video Service. This registration process can be accomplished using either GraphQL queries or messaging.

To proceed with the API or message-based registration, you’ll require a JWT obtained from the Identity Service. For detailed instructions on authenticating a service account and obtaining the necessary JWT, please refer to the guide on authenticate a service account.

Register Custom Videos via GraphQL​

To access the Video Service API for registering your pre-encoded videos, simply open your web browser and navigate to https://video.service.eu.axinom.net/graphiql.

To initiate the registration process for one of your pre-encoded videos, use the createCustomVideo mutation. The mutation

mutation RegisterVideo {
  createCustomVideo(
    input: { video: {
      title: "Big Buck Bunny", 
      customId: "my-reference-id-123"
      sourceLocation: "big-buck-bunny-folder", 
      sourceFileName: "BigBuckBunny",
      sourceFileExtension: ".mp4",
      sourceSizeInBytes: "276134947",
      dashManifestPath: "https://mystorage.blob.core.windows.net/publish  UrzEJZiLhQaERWJcbPH2yb/cmaf/manifest.mpd", 
      hlsManifestPath: "https://mystorage.blob.core.windows.net/publish  UrzEJZiLhQaERWJcbPH2yb/cmaf/manifest.m3u8", 
      audioLanguages: ["en"],
      subtitleLanguages: [],
      captionLanguages: [],
      outputFormat: CMAF,
      cmafSizeInBytes: "626659161", 
      lengthInSeconds: 634.53333,
      finishedDate: "2023-09-10T11:51:24.512948+00:00", 
      isProtected: true     
    }}
  ) {
    video {
      id
      title
    }
  }
}

The title and the source location are mandatory fields. The source location is again used to make sure that a video from one source can only exist once in the Video Service.

While the title and source location are mandatory, you have flexibility with other fields. You can either include them during the initial createCustomVideo mutation or update them later using updateCustomVideo mutation. It’s important to note that videos created during encoding via the Axinom Encoding Service cannot be modified in this way, as the encoder already provides all the relevant values.

In addition to the video itself, you can also declare the streams within the encoded video. For this, you can use the mutations createCustomVideoStream, updateCustomVideoStream, and deleteCustomVideoStream.

mutation DeclareVideoStream {
  createCustomVideoStream(
    input: { videoStream: {
      videoId: "e1a17517-dcee-4cf7-9edd-e0250e282156", 
      label: "HD", 
      format: CMAF, 
      type: VIDEO, 
      bitrateInKbps: 3000, 
      codecs: "H264", 
      displayAspectRatio: "16:9", 
      file: "cmaf/video-H264-1080-3000k-video-avc1.mp4", 
      frameRate: 30, 
      height: 1080, 
      pixelAspectRatio: "1:1", 
      width: 1920
    }}
  ) {
    clientMutationId
  }
}

This mutation is used to declare the different bitrate video streams of type "VIDEO" but also for defining your audio streams, subtitle streams, and closed caption streams.

Register Custom Videos via Messaging​

Another approach, distinct from utilizing the GraphQL API, involves dispatching an ImportCustomVideoCommand through the Message Bus. This message registers your pre-encoded video in the Axinom Video Service. It combines both the data of the video as well as all the different bitrate video streams, audio streams, subtitle streams, and closed caption streams.

See the section further up or see the Messaging How-to guide on how to send commands.

Example message payload
{
  "custom_id": "bunny123",
  "title": "Big Buck Bunny",
  "is_protected": false,
  "source_file_name": "big_buck_bunny.mp4",
  "source_file_extension": "mp4",
  "source_location": "big-buck-bunny-folder",
  "source_size_in_bytes": 102400000,
  "audio_languages": ["en", "fr"],
  "subtitle_languages": ["en", "fr", "de"],
  "caption_languages": ["en"],
  "video_bitrates": [2500, 5000, 8000],
  "hls_size_in_bytes": null,
  "dash_size_in_bytes": null,
  "cmaf_size_in_bytes": 626659161,
  "hls_manifest_path": "https://mystorage.blob.core.windows.net/publish/UrzEJZiLhQaERWJcbPH2yb/cmaf/manifest.m3u8",
  "dash_manifest_path": "https://mystorage.blob.core.windows.net/publish/UrzEJZiLhQaERWJcbPH2yb/cmaf/manifest.mpd",
  "length_in_seconds": 634.53333,
  "finished_date": "2023-09-12T14:30:00Z",
  "output_format": "CMAF",
  "video_streams": [
    {
      "label": "HD",
      "format": "CMAF",
      "type": "VIDEO",
      "file": "hd/init.mp4",
      "key_id": "key123",
      "iv": "iv456",
      "bitrate_in_kbps": 5000,
      "file_template": "hd/$Number$.ts",
      "codecs": "H.264 (AVC)",
      "frame_rate": 30,
      "height": 720,
      "width": 1280,
      "display_aspect_ratio": "16:9",
      "pixel_aspect_ratio": "1:1",
      "sampling_rate": 44100,
      "language_code": "en",
      "language_name": "English"
    },
    {
      "label": "audio",
      "format": "CMAF",
      "type": "AUDIO",
      "file": "audio/init.mp4",
      "bitrate_in_kbps": 128,
      "language_code": "en",
      "language_name": "English"
    },
    {
      "label": "subtitle",
      "format": "CMAF",
      "type": "SUBTITLE",
      "file": "subtitle/init.vtt",
      "language_code": "es",
      "language_name": "Spanish"
    }
  ]
}

With such a command you can ingest a large number of existing videos to integrate them easily for further usage in your Mosaic Solution or other services.