SmartPVR

The SmartPVR service (smpvr) allows the IPTV operator to implement the network personal video recorder (nPVR) service. Upon the subscribers’ requests the service generates TV programs from the records made by the Conveyor service based on the requested channel and time of the broadcast. The programs generation and management are performed by the SmartPVR service using the RPC methods.

In order for SmartPVR to generate a program, it needs to set the appropriate task via CreateProgram RPC method. Tasks are entered into the local database and preserved when you restart SmartPVR.

With the frequency specified in the configuration file parameter program_write_period, SmartPVR checks the database, generates and writes to the data_storage storage those programs, for which the following is specified in the task:

• scheduled state,
• the end time is earlier than the current time (such programs must already be fully recorded by the Conveyor service).

IMPORTANT: the program is recorded with the configuration set for the channel at the time of the generation task, and not at the time of setting the task or channel recording. Changes to the channel configuration between the time the task is created and the task is run remain the responsibility of the person who made the change.

Command Line Parameters

–help, -h

Display help in the console and exit.

–version, -v

Display version in the console and exit.

–config-file, -c

Required: true

The configuration file path.

–console-log

Ignore log-config and log-file and print the log to the console with the default formatting.

–log-config, -l

Default value: smartPVR.log.json

The path to the logger configuration file.

–log-file

Default value: smartPVR_%Y-%m-%d_%H-%M-%S.%N.log

The logger output file. It is taken into account only if the logger configuration is not specified.

The following variables can be used in the file name:

• Y — year,
• m — month,
• d — day,
• H — hour,
• M — minute,
• S — second,
• N — the file number among files with the same name.

Configuration File

The location of the configuration file by default: /opt/smartlabs/smartmedia/smartPVR/config/config.json

Basic Parameters

threads, integer 

Default value: 2

The number of worker threads.

processing_threads, integer 

Default value: 5

The number of processing threads in the pool used to record programs into the storage.

rpc_port, integer 

The port of the RPC server. If greater than 0, the RPC server is enabled. By default, the RPC server is disabled.

data_storage, section 

The section describing the way of storing recorded programs and its settings. Only one way can be specified.

fs, section 

The section with settings for storing programs in the local POSIX file system (FS).

program_root, string 

Default value: ./programs

The path to the storage of generated programs in the local POSIX file system.

s3, section 

The section with settings for storing programs in the S3 compatible storage.

tmp_dir, string 

The path in the local POSIX file system for storing temporary files, which are subsequently copied to S3 compatible storage.

remove_failed_data, boolean 

Default value: false

Flag to remove temporary files if recording the program to S3 compatible storage failed.

remote_path

Default value: /pvr

Relative path to S3 storage for storing program files.

host, string 

The address (hostname or IP address) of the S3 storage server.

bucket, string 

S3 storage bucket name.

access_key_id, string 

S3 storage access key ID.

access_key, string 

S3 storage access key.

sm, section 

Section with settings for uploading programs to storage via the load balancer server.

tmp_dir, string 

The path in the local POSIX file system for storing temporary files.

remove_failed_data, boolean 

Default value: false

Flag to remove temporary files if recording the program to server failed.

addr, string 

IP address of the server.

port, integer 

Port of connection to the load balancer service.

events_table, integer 

Name of the MongoDB collection from which events to be added to the program playlist are requested. Events are assumed to be stored in the MongoDB database, which contains information about the chunks and headers of the channel that the program is being recorded from.

program_status_storage_url, string 

URL of the MongoDB database containing the settings of a job created by the CreateProgram RPC method. The programs are generated based on database data. This database data is also used to respond to other RPC methods described below. The supported URL protocol — mongodb://

program_storage_mongo_db, string 

Name of the MongoDB database containing settings and statuses of programs.

program_storage_mongo_collection, string 

Name of the MongoDB collection containing settings and statuses of programs.

program_storage_mongo_program_id_collection, string 

Name of the MongoDB collection containing the program_record_id counter for generating monotonically increasing integer program IDs. MongoDB does not support the “autoincrement ID” functionality common to relational DBMSs. Therefore, it is necessary to explicitly store the counter value in a separate collection in order to restore it after restarting the service. For more information, see the article “Generating Globally Unique Identifiers for Use with MongoDB”.

key_url_template, string 

Default value: empty string

The mask string to generate an encryption URL key. The following mask substrings will be replaced:

• ${POSITION} — the timestamp for which the key should be requested. Does not coincide with the current playback time due to the keys rotation;
• ${RESOURCE-ID} — the channel identifier;
• ${TYPE} — currently always replaced with VOD.

Example: http://11.22.22.22:12345/key?r=${RESOURCE-ID}&t=${TYPE}&p=${POSITION}

recrypt_uri_prefix, string 

Default value: empty string

Used to encrypt MP4 chunks on-the-fly using the SmartMEDIA Recryptor service. For example, from the Common Encryption ‘cenc’ (AES-CTR) scheme to the ‘cbcs’ (AES-CBC Pattern Encryption) scheme. This allows a single copy of encrypted content to be stored and played by players using both Widevine DRM (‘cenc’) and Apple FairPlay DRM (‘cbcs’). The prefix is added before the URI of the encrypted chunks in HLS media playlists so that the client requests the chunks from the SmartMEDIA Recryptor service. The prefix is only added if the chunks are encrypted with the ‘cenc’ scheme for Widevine DRM.

When a prefix is used, a special suffix “/[start]-[end].mp4” (e.g. “media.mp4/0-814.mp4”) is added to the URI instead of the #EXT-X-BYTERANGE element. To the player and the HTTP server it looks like a request for a separate file, not a ‘byte range’ request. This is necessary because when re-encrypting and repacking the size of the MP4 chunk may change. Then the “Content-Range” range in the response will not match the “Range” range in the HTTP request and this will lead to an error and stop the player. Imitating individual files in a playlist solves this problem, although the chunks may physically be written to a single file on disk and SmartMEDIA Recryptor accesses them using ‘byte ranges’. This setting is used only for HLS and does not affect DASH generation.

program_write_period, time units 

Default value: 1h

The frequency of processing tasks from the database (program_status_storage_url).

min_program_duration, time units 

Default value: 1m

The minimum acceptable duration of the program.

max_program_duration, time units 

Default value: 1d

The maximum acceptable duration of the program.

max_programs_in_rpc_response, integer 

Default value: 100 000

The maximum number of programs that the GetPrograms. RPC method can return. This parameter allows to prevent critical slowdowns of the SmartPVR service in case of incorrect programs’ request.

rpc_program_url_prefix, string 

Default value: empty string

The programs’ URL prefix.

channel_index, section 

See the description of the channel_index section for the Conveyor service.

channel_index → channel_tables, Array of strings 

Array of collection names in the MongoDB database with channel recording settings. If multiple Conveyor services are used for recording channels, each service uses a separate collection. And the SmartPVR service searches for a channel to record the program across all the specified collections. This field is specific to the SmartPVR service only and is not included in the description of the channel_index section of the Conveyor service. If this setting is omitted, the collection name from the channel_table field is used.

enable_smooth_streaming, boolean 

Default value: false

Will create Microsoft SmoothStreaming playlist when value is true. Each chunk will be recorded to separate file.

Makes sense only with recording to mp4 container.

smooth_streaming_normalize, boolean 

Default value: false

When value is true the timestamps of the first chunk of each track will be normalized to zero regardless of their synchronization.

Makes sense only when enable_smooth_streaming is true.

output_dir_template, string 

Default value: empty string

Naming template of media tracks’ output directories.

When value is empty string recording will be performed to the directory with the same name as was configured for the corresponding track the original channel (see the parameter dir of the channel in Conveyor’s channel configuration).

Possible template placeholders are:

• {dir} — the directory name configured for the corresponding track in the original channel (see the parameter dir in Conveyor’s channel configuration);
• {type} — the track type (video, audio, text);
• {bitrate} — the bitrate of the corresponding original track (see the parameter bw in Conveyor’s channel configuration).

Example Configuration

JSON

{  “program_root”:“/video/programs”,  “rpc_program_url_prefix”:“http://myserver/programs/”,  “rpc_port”:49985,  “key_url_template”:“http://10.65.40.53:12684/CAB/keyfile?r=${RESOURCE-ID}&t=${TYPE}&p=${POSITION}”,  “min_program_duration”:5,  “program_status_storage_url”:“file:///video/programs/db_programs.db”,  “program_write_period”:“10s”,  “channel_index”: {    “uri”:“mongodb://localhost”,    “db”:“db_test”,    “channel_table”:“channels”,    “s3_storage_table”:“s3_config”,    “file_storage_table”:“file_config”,    “mongo_index_storage_table”:“mongo_config”  } }

Supported RPC Methods

See also the “RPC Methods Common to all Services” chapter.

CreateProgram(npvr_channel_id, utc_start_sec, utc_end_sec)

The method creates a job to generate a program from the content aired in the period between the utc_start_secand utc_end_sec timestamps on the npvr_channel_id channel. The content from the specified time interval is combined into a single asset.

Call Parameters

npvr_channel_id, string 

Channel ID.

utc_start_sec, integer 

Program start time, in seconds (UTC).

utc_end_sec, integer 

Program end time, in seconds (UTC).

The set of parameters npvr_channel_id, utc_start_sec, utc_end_sec must be unique. If you try to regenerate the program with parameters that match the already generated program, the method will return an error.

The program duration (the difference between utc_end_sec andutc_start_sec) must fit in the interval between min_program_duration and max_program_duration, otherwise the method will return an error.

Call Example

Python

rpcResult = recorder.CreateProgram(‘my_channel_id’, 1424767450, 1424767490)

Response Parameters

The method returns the following data:

status, string 

Program status:

• scheduled — the program has not been generated yet;
• in_progress — the program generation is currently in progress;
• complete — the program generated successfully;
• failed — the program generation failed.

program_id, integer 

Program ID.

npvr_channel_id, string 

ID of the channel on which the program was aired.

utc_start_sec, integer 

Program start time, in seconds (UTC).

utc_end_sec, integer 

Program end time, in seconds (UTC).

Response Example

ProgramStatus(program_id)

The method returns the status and other properties of the program generated using the CreateProgram method.

Call Parameters

program_id, integer 

Program ID returned by the CreateProgram method.

Call Example

Python

rpcResult = recorder.ProgramStatus(1)

Response Parameters

If the program with the specified program_id is not found, the method returns JSON “result”: “”. If the program exists, the method returns the fields similar to the CreateProgram method.

GetPrograms(status, npvr_channel_id, utc_start_sec_range, utc_end_sec_range)

The method returns the status and other properties of several programs generated using the CreateProgram method. The returned URLs of the playlists and the list of resources may not be valid, use the ProgramStatus method to clarify them.

Call Parameters

All parameters are optional.

status, string 

Program status: – scheduled — the program has not been generated yet; – in_progress — the program generation is currently in progress; – complete — the program generated successfully; – failed — the program generation failed.

npvr_channel_id, string 

ID of the channel on which the program was aired.

utc_start_sec_range, string 

Time interval at which the TV show started, in format: <integer number of seconds>-<integer number of seconds>. Examples: 1447718400-, 1447718400-1447718420, -1447718420.

Important: floating-point numbers are not supported. For example, 1447718400.0-1447718420 — an incorrect value.

utc_end_sec_range, string 

Time interval at which the TV show finished. The format is similar to the utc_start_sec_range parameter.

order_by, string 

The field by which the method response is ordered. Possible values: status, npvr_channel_id, utc_start_sec, utc_end_sec.

Call Example

Python

rpcResult = recorder.GetPrograms(npvr_channel_id =‘CH_TEST’, utc_start_sec_range =‘-1447169340’, order_by =‘program_id’)

Response Parameters

The method returns a list of programs, each of which contains a set of fields similar to the CreateProgram method.

Response Example

JSON

[  {    /*Firstprogramparameters*/    “status”:“in_progress”,    “npvr_channel_id”:“CH_TEST”,    “url”:“http://www.server.tv/22/playlist.mpd”,    “utc_end_sec”:“1447169540”,    “program_id”:“22”,    “streams”:“”,    “utc_start_sec”:“1447169340”  },  {    /*Secondprogramparameters*/  },  /*N-thprogramparameters*/  } ]

RemoveProgram(program_id)

The method removes either an already generated program or a scheduled job for program generation.

Call Parameters

program_id, integer 

Program ID returned by the CreateProgram method.

Call Example

Python

rpcResult = recorder.RemoveProgram(12)

Response Parameters

If successful, the method returns JSON “result”: “”.

HaveContent(npvr_channel_id, utc_start_sec, utc_end_sec)

The method returns the presence of a channel record (generated by the Conveyor) with the ID npvr_channel_id for the period between utc_start_sec and utc_end_sec. The method gets data from MongoDB (see the description of the channel_index section in the main Conveyor configuration).

Call Parameters

npvr_channel_id, string 

ID of the channel on which the program was aired.

utc_start_sec, integer 

Program start time, in seconds (UTC).

utc_end_sec, integer 

Program end time, in seconds (UTC).

The period (the difference between utc_end_sec and utc_start_sec) must fit in the interval between min_program_duration and max_program_duration, otherwise the method will return an error.

Response Parameters

The method return the following data::

availability_percent, string 

The amount of content in storage as a percentage of all the content you are looking for for the period utc_start_sec – utc_end_sec.

Usage Example

If the content is completely recorded, after the following call:

Python

rpcResult = recorder.HaveContent(‘my_channel_id’, 1424767450, 1424767490)

the following is returned in the rpcResult:

JSON

{  “availability_percent”:100.0 }