Interactive Script Commands Dictionary¶
The table list and describes all currently supported interactive service script commands which can be used in script that run on the RPM on version 5.5 and above.
Supported Commands¶
Name |
Command Syntax |
Description |
Remote Control (R/C) |
Any R/C command, e.g., dial-number, EXIT, MENU, INFO |
R/C commands as broadcast from the interactive menu or the virtual R/C. Used to dial channels and navigate through menus (RIGHT, UP, EXIT…) Concatenate R/C (level) commands with commas (,) unless pauses are needed in between Separate from script (level) commands with semi-colon (;) Example: EXIT, MENU, RIGHT, UP; P(7); DOWN, UP; |
Pause |
P(<duration>) |
Insert a pause in the script execution. Used when waiting for a banner or menu to appear/disappear. Should be separated from all other commands using a semi-colons (;) Parameters: Duration: number of seconds to pause |
Detect |
D(BS(..), SS(…)) |
Monitor one or more detectors for A/V quality to detect alerts. Multiple detectors inside the D() command are separated by commas. Separate from all other script level commands with semi-colons (;) |
Black Screen Detector |
BS([<left>], [<top>], [<width>], [<height>],<duration>, <threshold>) |
Run the black screen detector. Alert will be registered for BS if measured values exceed the threshold (configured) parameter for longer period than the duration (configured) parameter Parameters: Threshold: measured in black pixels percentage of screen Duration: (seconds) minimum time necessary for the measured values to exceed threshold continuously. The first 4 parameters (optional) provide a way to monitor only the “Alert Region” of the screen @2.5.1 though when specifying the region all 4 parameters should appear together. Note: all detectors are built such that they will complete right away if the measured values are within the thresholds for A/V (are OK); i.e., the D command might complete executing in under a second if all detectors return OK |
Static Screen Detector |
SS[<left>], [<top>], [<width>], [<height>],(<duration>, <threshold>) |
Similar to a BS but detects (measures) the static screen between two consecutive frames. The “Alert Region” @2.5.1 parameters are the same as above. |
Motion Screen Detector |
MS[<left>], [<top>], [<width>], [<height>],(<duration>, <threshold>) |
Complement of SS detecting motion and alerting for percent of screen movement which is greater than the set threshold. The “Alert Region” @2.5.1 parameters are the same as in BS above. |
Low Audio Detector |
LA(<duration>, <threshold>) |
Alert if audio level drops below the specified threshold (dB) for the configured duration (in seconds) |
High Audio Detector |
HA(<duration>, <threshold>) |
Alert if audio level goes above below the specified threshold (dB) for the configured duration (in seconds) |
Find |
F(<imagePath>, <timeout>) |
Match a pre-captured image (with image at the specified location on the screen) to verify its existence within the live video being logged. This command is only available for customer who purchased the interactive services module, and can only be created using the IS Wizard application. Parameters: ImagePath: contains the path and the name of the image to be matched. This is created automatically by the IS wizard. Duration: (in seconds) to try get a match before timeout |
Negative Find |
N(<ImagePath>, <timeout>) |
Same as F() above, only that this command returns TRUE if the image does NOT exist within the captured video. (Included in the interactive services module) Parameters: same as for F() command |
Step |
S(<ImagePath>, <timeout>, <R/C command>, <# of repeats>) |
Step through an interactive menu until a certain image is detected. This command will try to find a match multiple times, each time iterating through the menu according to the parameters set for it. (Included in the interactive services module) Parameters: ImagePath: same as above Timeout: (seconds) time used to find a match. This timeout will start and be exhausted on every iteration through the menu R/C command - sent between matches to iterate menu commands # of repeats: - of R/C commands to try find a match |
Program Not Available |
NA(F(…)[,N(…)][,D(…)]) |
Encapsulating commands such as F(), N() and D() (for image recognition of splash screens) indicating the availability of underlying services and if unavailable stops the execution of the enclosed detector scripts (D(BS, SS…)) without reporting any faults. The main use case is on services that have only limited availability. When not available a splash screen appears with “Service unavailable” that the NA() command recognizes to prevent detection of invalid faults (e. g., static screen) Parameters: One or more F() or N() commands looking for specific images on the screen and D((BS, SS…))detector enclosed commands to detect of A/V faults Usage example: EXIT, %DIALNUMBER%;NA(myscript/ProgNotAvail, 7);P(3);D(BS(30,95),SS(30,95)); => Detect black-screen and static-screen if ProgNotAvail image does not show up on the screen. If it does, continue scanning without reporting anything |
Banner |
B(<ImagePath>, <timeout>) |
The banner command is basically the F() command but whose results are different. It is designed to match a part of the STB banner. If the command fails (no banner is detected), the system will initiate a power cycle on the STB. At first the R/C power command is used but if not effective, it is followed by a cold power reset through the IP power switch (if such is setup on the system). Parameters: same as F() command |
Supported Variables¶
The following variables used in scripts get replaced by the system during runtime.
Name |
Syntax |
Description |
Dial Number |
%DIALNUMBER% |
Generic variable replaced at runtime to reflect channel specific dial numbers (see example above) |
STB |
%STB% |
Generic variable replaced at runtime to reflect the STB specific image locations For example in a script command %STB% variable: F(%STB%/imageMatch1, 7) Gets translated to: F(UnitedCableSTB/imageMatch1, 7) or (HorizonNetSTB/imageMatch1,7) Depending on the STB used, the right scanner image location gets selected |
Example: A generic script can be created with the %DIALNUMBER% variable to run on all the channels of a lineup without channel specific hard-coding. Then at runtime just before dialing, the variable gets translated to the actual channel numbers through the (bouquet) table lookup.
Script Editing¶
The web front end provides a simple script editor whose context sensitive “Scripting Help” @2.5 (in Help sidebar) should be read before any editing. Please note that the editor does not check the syntax of scripts edited manually, though it will usually create a fault clip of type SCRIPT- ERROR and point to the offending command such as Command: (P7) in example below:
For example:
SCRIPT ERROR Command: (P7). Channel: 123 MTV. R-Encoder: ENC7@MyProbe1. Script: INFO,123;(P7);D(BS(30,95));. ScriptName: MyFaultyScript. Scanner: ENC7. Ref: RPM-120440
Commas vs. semi-colons¶
The “B” is an R/C command while the P(<number>) is a script command and those should be separated from each other by semi-colons. Commas are used only to separate consecutive R/C commands.
The script editor distinguishes between the B as it expected a banner command such as B(path/image, 7)
Example: EXIT,801;P(5);B;P(10);0000;P(5);D(BS(15,95),SS(15,95),LA(15,-40),HA(15,-1));
Other Examples¶
Default script with Static Screen enabled
EXIT,%DIALNUMBER%;NA(F;P(5);D(BS(30,96),SS(30,95),LA(30,-40),HA(30,-1));
Default script with Moving Screen enabled
EXIT,%DIALNUMBER%;NA(F;P(5);D(BS(30,96),MS(30,95),LA(30,-40),HA(30,-1));
Here the moving screen is defined instead of the static screen