4 DIVA Transcode Service

This chapter discusses the new DIVA Transcode Service introduced with DIVAdirector 5.3.

Introduction

Oracle DIVAdirector 5.3 introduces a new transcode service to the system. The service contains two main components. The first component is a RESTful API for submitting and viewing requests, and viewing currently configured transcoder information (name, version, and so on). The second component is a time-based background process that executes periodically to update the progress and state of all actively transcoding requests.

The Root Path must point to a location that the currently configured transcoder implementation service can read. However, the new transcode service does not need read access to the location. To clarify the distinction between the new transcode service and the transcoder implementation, the transcode service provides a common interface for multiple transcoder implementations (for example Vantage, FlipFactory, and so on). The transcoder implementation (for example the Vantage service) requires read access to the Root Path.

The transcode service API is in a self-hosted Open Web Interface for .Net (OWIN) application and contained in a Windows service - removing any dependency on IIS. The request information is held in a SQL Server Express LocalDB database that is installed with the service installer, and accessed by the data layer through a common interface.

To use the transcoder service, users select transcodeSvc as the source or destination when submitting requests. To configure the new transcode service correctly, the Source Name must match the DIVAdirector TranscodeSourceDestName configuration value, and the Connect Options entry does not include any of the tr flags (for example tr_restore_format, tr_names, and so on).

Web Configuration File

The new transcoder service requires several changes to the DIVAdirector Web configuration. The web configuration file is located in the installation's www folder. For example C:\Program Files (x86)\DIVAdirector 5\www\Web.config.

The setting updates are as follows:

DIVArchive Web Services (WS) Endpoint

You can configure the WS Endpoint to any available port.

<add key="DIVArchiveAPIUrl" value="http://10.80.106.57:9763/services/DIVArchiveWS_REST_2.1/" />
appname

This identifies the name of the application to be registered in the DIVArchive WS API interface. Specifically, the value of the appName parameter passed to the registerClient method. This is required before interfacing with the DIVArchive WS API. For example:

<add key="appName" value="DIVAdirector" />
TranscodeSourceDestName

This identifies the name of the preconfigured source or destination that defines the DIVArchive restore location to be used by DIVAdirector for creating proxies with the transcoding service.

<add key="TranscodeSourceDestName" value="transcodeSvc"/>

Windows Services

The DIVAdirector Windows service installed along with the web application handles background tasks performed outside of the context of a web request (for example proxy creation, metadata extraction, drop folder monitoring, and so on). The Windows Management Console displays the legacy service as DIVAdirector Server Service.

Background task functionality is being migrated away from the legacy service to a new service. The new Oracle.DIVAdirector.TaskManager service currently handles only a subset of the functionality and therefore both services will be installed by the DIVAdirector installer until the legacy service has been fully migrated.

The Oracle.DIVAdirector.TaskManager service configuration file, Oracle.DIVAdirector.TaskManager.exe.config, is located in the C:\Program Files (x86)\DIVAdirector 5\TaskManager\ folder.

The configuration file has four main sections that need attention as describe below.

  1. DIVArchive Web Services API REST Endpoint Configuration

    Four settings require configuration in the <appSettings> section:

    applicationName

    This is the name of the application to be registered in the WS API interface. Specifically, this is the value of the appName parameter passed to the registerClient method. This is required before interfacing with the WS API.

    <add key="applicationName" value="app name" />
    locationName

    This identifies the physical location where the computer running the client is located. Specifically, the value of the locName parameter passed to the registerClient method. This is required before interfacing with the WS API.

    <add key="locationName" value="location name" />
    processID

    This identifies the process ID number used for registering the client application. Specifically, the value of the processID parameter passed to the registerClient method. This is required before interfacing with the WS API.

    <add key="processId" value="1234" />
    DIVArchiveApiUrl

    This identifies the WS API REST endpoint. You can use any available port number for the endpoint.

    <add key="DIVArchiveApiUrl" value="http://10.80.106.57:9763/services/DIVArchiveWS_REST_2.1/" />

  2. Transcoder Service Access Configuration

    Three settings require configuration in the <TranscodeSettingsConfigurationSection> section:

    TranscoderClientSettings

    The TranscoderApiUrl is the url of the transcode service base API endpoint. An optional integer LocationId can be added to TranscoderClientSettings to override the default location.

    <TranscoderClientSettings TranscoderApiUrl="http://localhost:9876/api/">
    PresetName

    The PresetName is the name of a preset configuration in the transcoder service. A preset is a name associated with a preset ID (for example a Vantage workflow ID).

    PresetName="Default Video Proxy"
    ProxyableFileExtensions

    ProxyableFileExtensions is the list of file extensions for which the service will try to create a proxy.

    ProxyableFileExtensions="mxf,lxf,avi,mpg,mpeg,mov,mp4">

    The following list of parameters is being passed to the preset workflow defined by PresetName. You can add more parameters to this list as needed without any code changes.

    <Parameters>
<Parameter Key="GenerateKeyFrames" Value="True" />
<Parameter Key="KeyframeCaptureInterval" Value="00:00:01:00@29.97" />
</Parameters>

  3. Task and Task Interval Configuration

    The following tasks are configured in the <ScheduledTasks> section and run by the Windows Service. You cannot disable any of these tasks without losing functionality. However, you can tune an interval timer with the IntervalInSeconds parameter to achieve better performance.

    TranscodeOnRestoreCompleteTask

    This task polls the progress of a DIVArchive Restore request (through the DIVArchive Web Services (WS) API REST endpoint), and initiates a Transcode request upon completion. This task is also responsible for calling the Proxy Creation Service.

    <ScheduledTask Name="TranscodeOnRestoreCompleteTask" Type="Oracle.DIVAdirector.TaskManager.Tasks.TranscodeOnRestoreCompleteTask, Oracle.DIVAdirector.TaskManager" IntervalInSeconds="10" Enabled="true" />
    UpdateRequestsStatusTask

    This task monitors and updates the state and progress of all active DIVArchive requests.

    <ScheduledTask Name="UpdateRequestsStatusTask" Type="Oracle.DIVAdirector.TaskManager.Tasks.UpdateRequestsStatusTask, Oracle.DIVAdirector.TaskManager" IntervalInSeconds="10" Enabled="true" />

  4. Postgres Database Communication Configuration

    This connection string should use the same server and credentials as the connection string defined in the DIVAdirector web application's web.config file.

    <connectionStrings>
<add name="DIVADirectorContext" connectionString="Server=localhost;Database=DIVAdirector;User Id=postgres;Password=Manager;" providerName="Npgsql" />
</connectionStrings>

Database Settings

WARNING:

Oracle highly recommends not performing these modifications without having an Oracle Support Technician present.

There are several configuration settings stored in the LocalDB that can only be modified by directly modifying database rows.

Transcoder Settings

The following transcoder settings can be modified directly in the database:

  • TranscoderSettings.Transcoder stores the name of the current transcoder implementation. Vantage is the only transcoder supported in this release.

  • VantageSettings.Host stores the name of the computer running the Vantage SDK Service.

  • VantageSettings.Port stores the port number used by the Vantage SDK Service.

  • VantageSettings.MetadataActionDescriptions stores the descriptions of actions in the Vantage workflow that expose metadata variables that should be associated with a job.

Vantage Transoder DB Settings

Presets

The Presets table stores a named mapping to a transcoder implementation's internal workflow identifier. For Vantage, the InternalId is the workflow identifier.

Surrounding text describes c4_presets.jpg.

The CheckStatusOnStartup parameter is a Boolean flag indicating a required preset that must be checked during service startup. A warning will be logged if CheckStatusOnStartup is set to true and the preset is not found. The service will attempt to activate the preset if CheckStatusOnStartup is to true and the preset is found but not active. The transcode log files will have entries for this check and attempted activation.

Surrounding text describes c4_logfile.jpg.

Locations

The Locations table stores a set of predefined output storage locations. The transcode service will only accept jobs with a valid storage location. If no location is specified in the transcode request, the service will attempt to find a location using IsDefault (if set to true) and use that location. Log files will indicate that no location was specified, and the default value used.

The Path column stores the path associated with the location. This value will form the base output path for the transcoded job. The remainder of the path will be formed by the Job ID returned from the transcode service. For example if the location path is \\10.80.106.91\c$\Users\Administrator\Desktop\output\Dev and a Job ID 6449d0db-2377-4e3d-a969-be09a742a63d is returned from the transcode service, then the final output path for the transcoded file will be \\10.80.106.91\c$\Users\Administrator\Desktop\output\Dev\6449d0db-2377-4e3d-a969-be09a742a63d.

API Endpoints

There are two REST main endpoints that are configured by modifying the database entries:

  • /api/transcoder is used for viewing currently configured transcoder information.

  • /api/jobs/[jobId] is used for viewing job progress and submitting new jobs.

Example #1

To create a new transcode job the request is as follows:

HTTP POST to /api/jobs
{    
    "inputFilePath": " \\rootPath\InputFileMXF",
    "output":{
        "presetName": "Default Video Proxy",
        "parameters": [
            {
                "name": "GenerateKeyFrames",
                "value": "True"
            },
            {
                "name": "KeyframeWidth",
                "value": "128"
            }, ….
        ]
    }
}

The response to the request is as follows:

201 Created
Headers: 
…. Location: http://localhost:9876/api/jobs/794660fe-2c37-491c-b7a9-7fe27f2c6346....
Body:
{
  "jobId": "794660fe-2c37-491c-b7a9-7fe27f2c6346",
  "internalId": "57d0a08b-fa5f-4ff7-8177-c1d2d4adf92a",
  "inputFilePath": "\\rootPath\InputFileMXF",
  "outputFilePath": null,
  "status": 8,
  "createdDate": "2015-08-13T10:26:06.5553211-06:00",
  "createdBy": null,
  "updatedDate": "2015-08-13T10:26:06.5553211-06:00",
  "updatedBy": null,
  "progress": 0,
  "metadata": null,
  "output": {
    "id": 11,
    "presetName": "Default Video Proxy",
    "location": {
      "id": 1,
      "name": "Default Location",
      "path": "\\10.80.106.91\c$\Users\Administrator\Desktop\output\Dev",
      "isDefault": true
    },
    "parameters": [
      {
        "id": 40,
        "name": "GenerateKeyFrames",
        "type": null,
        "value": "True"
      },
      {
        "id": 43,
        "name": "KeyframeWidth",
        "type": null,
        "value": "128"
      },
      {
        "id": 45,
        "name": "OutputFileName",
        "type": null,
        "value": "AA004001"
      }
    ]
  }
}

Example #2

To get all jobs summaries the request is as follows:

HTTP GET TO /api/jobs

The response to the request is as follows:

[
  {
    "jobId": "2ebbd1e9-b404-4909-944e-8d48c0a4b370",
    "internalId": "57d0a08b-fa5f-4ff7-8177-c1d2d4adf92a",
    "inputFilePath": "C:\Users\Administrator\Desktop\watch\AA004001.MXF",
    "outputFilePath": "\\10.80.106.91\c$\Users\Administrator\Desktop\output\Dev\2ebbd1e9-b404-4909-944e-8d48c0a4b370\AA004001.mp4",
    "status": 6,
    "createdDate": "2015-08-13T10:26:06.557",
    "createdBy": null,
    "updatedDate": "2015-08-13T10:26:26.067",
    "updatedBy": "TaskManager",
    "progress": 100
  },
  {
    "jobId": "25970df1-7f60-4f65-8ee9-49b83b908364",
    "internalId": "44c54311-da47-443f-b7e2-21c56c247e0e",
    "inputFilePath": "C:\Users\Administrator\Desktop\watch\AA004001.MXF",
    "outputFilePath": "\\10.80.106.91\c$\Users\Administrator\Desktop\output\Dev\25970df1-7f60-4f65-8ee9-49b83b908364\AA004001.mp4",
    "status": 6,
    "createdDate": "2015-08-13T10:19:26.28",
    "createdBy": null,
    "updatedDate": "2015-08-13T10:19:50.687",
    "updatedBy": "TaskManager",
    "progress": 100
  }]

Example #3

To get job details the request is as follows:

HTTP GET to /api/jobs/794660fe-2c37-491c-b7a9-7fe27f2c6346

The response to the request is as follows:

{
  "jobId": "794660fe-2c37-491c-b7a9-7fe27f2c6346",
  "internalId": "57d0a08b-fa5f-4ff7-8177-c1d2d4adf92a",
  "inputFilePath": "C:\Users\Administrator\Desktop\watch\AA004001.MXF",
  "outputFilePath": "\\10.80.106.91\c$\Users\Administrator\Desktop\output\Dev\2ebbd1e9-b404-4909-944e-8d48c0a4b370\AA004001.mp4",
  "status": 6,
  "createdDate": "2015-08-13T10:26:06.557",
  "createdBy": null,
  "updatedDate": "2015-08-13T10:26:26.067",
  "updatedBy": "TaskManager",
  "progress": 100,
  "metadata": "[{\"Key\":\"Container Format\",\"Value\":\"Material Exchange Format (OP-1a)\"},{\"Key\":\"Content Duration\",\"Value\":\"00:00:08:04@25\"},{\"Key\":\"Video Framerate\",\"Value\":\"25\"},{\"Key\":\"Header Timecode\",\"Value\":\"01:06:18:15@25\"},{\"Key\":\"OutputFileFullPath\",\"Value\":\"\\\\10.80.106.91\\c$\\Users\\Administrator\\Desktop\\output\\Dev\\2ebbd1e9-b404-4909-944e-8d48c0a4b370\\AA004001.mp4\"}]",
  "output": {
    "id": 11,
    "location": {
      "id": 1,
      "name": "Default Location",
      "path": "\\10.80.106.91\c$\Users\Administrator\Desktop\output\Dev",
      "isDefault": true
    },
    "presetName": "Default Video Proxy",
    "parameters": [
      {
        "id": 40,
        "name": "GenerateKeyFrames",
        "type": null,
        "value": "True"
      },
      {
        "id": 43,
        "name": "KeyframeWidth",
        "type": null,
        "value": "128"
      },
      {
        "id": 45,
        "name": "OutputFileName",
        "type": null,
        "value": "AA004001"
      }
    ]
  }
}