INGEST API - Socket Commands

Owned by Ayça Vural (Unlicensed)
Last updated: Oct 10, 2024 by Mustafa Yılmaz
7 min read

Using third party applications, users can easily connect to Ingest. In this section, we will use Telnet application to connect to Ingest. As shown on the figure below, the computer running Ingest has been connected to Telnet. In order to access to Ingest, the user should enter the command;

Web/Rest API commands are available as well, Please contact tech support (support@metus.com) to get it. 

o <hostname> <portnumber>

o : open

host name: the name or IP of the computer running Ingest

port number: the port to which third party applications connect to Ingest (please see Remote Control settings. )

Where Ingest is computer name, example Metus1.

Ingest has two responses to TCP commands;

FAILED: shows that the command couldn’t be executed successfully. The user has not defined any profile for ‘Encoder 1’ as shown on the first command below, so that this encoder can’t be started without any profile.

OK: shows that the command is executed without any problem. The user has defined a profile to start successfully.


1.EncStatus [encoder name]  : Displays status of an encoder.

Example: (The commands user entered has been shown in bold text)

EncStatus TestEncoder1 

OK: TestEncoder1:Prepared

The possible results of EncStatus [encoder name] command;

No encoder exists : no encoder has been defined yet.

None: indicates that the encoder has been disposed.

Running: shows that recording has just been started.

Runned: shows that Ingest has been capturing the media source.

Stopping: indicates that recording has just been stopped.

Stopped: indicates that the current encoder stopped capturing.

Pausing: shows that recording has just been paused.

Paused: shows that the encoder paused capturing.

Preparing: indicates that the user has just defined either encoder or encoder and its profile.

Prepared: indicates that the user has defined either encoder or encoder and its profile

Splitting: indicates that the user has clicked <split> button.

Splitted: shows that recording has been splitted.

Error: shows that error has just been found.


2.EncStatus : Displays status of all encoders.

EncStatus

EncStatus XDCAM OK: XDCAM:Stopped

EncStatus "MPEG2 HD" OK: MPEG2 HD:Stopped


*Two encoder with names XDCAM and MPEG2 HD have been defined and they are in “Stopped”
state.


3. SignalStatus [encoder name]: Shows signal status of selected encoder.

SignalStatus "Encoder 1"
OK: Encoder 1 Signal Status
Video Signal: Exists


4.List [encoder name]  : Lists all profiles of an encoder and their modes.

List TestEncoder1

OK:

Profile 1: MPEG-2 PAL

Record duration : 00:00:00

File name : [preset][date][time]

Encoder Status : ES_Prepared

Overlay : No overlay

Profile 2: MPEG-2 HD High PAL

Record duration : 00:00:00

File name : [preset][date][time]

Encoder Status : ES_Prepared

Overlay : No overlay

Profile 3: VCD PAL

Record duration : 00:00:00

File name : [preset][date][time]

Encoder Status : ES_Prepared

Overlay : No overlay


*As you see three profiles have been defined for this encoder TestEncoder1. The user can see all properties of the profiles with this List command.


5.List : Lists encoders

List

OK:

TestEncoder1 Mode: Quick

720x576 25,00 fps, 2 Ch. 48000 Hz

No stream


*The user can see all encoders defined for Ingest and their related properties.


6.Load [file name] : Loads project

Load "C:\Program Files\Metus Technology\Metus Ingest 4.X\Projects\sources.mi2prj"

OK: Project close succeeded

Project load succeeded.


*The user should type the full path of the file name to load the project, and the path should be in double quotations. As you see, Load command closes the current project and then loads the related project.


7.Overlay [encoder name] [overlay name] [overlay text] : Changes the overlay text of an encoder.

Overlay Encoder1 overlay1 _date_time_frame

OK: Overlay text of Encoder 'Encoder1' was changed succesfully.

Note: Variable Text must be enabled in overlay settings.

*The user has changed the text of the overlay1 for Encoder1 as _date_time_frame


8.Pause [encoder name] : Pauses all profiles of an encoder.

Pause "Encoder 1"

OK: Encoder has been paused succesfully.


9.Pause [encoder name] [profile index] : Pauses profiles.

Pause "Encoder 1" 1

OK: Profile has been paused succesfully.


*The first profile for Encoder 1 has been paused. Because of the space in profile name, double quotations have been used.


10.Pause : Pauses all encoders.

Pause

OK: OK: Encoder has been paused succesfully.

OK: Encoder has been paused succesfully.


*Two encoders have been paused with this command.


11.Preview [encoder name] [on/off] : Enables or disables preview for an encoder.

Preview "Encoder 1" on

OK:


*The preview for Encoder 1 has been set to on, so the user can view source media from Ingest.


12.Preview [on/off] : Enables or disables preview for all encoders.

Preview off

OK: Encoder Preview is Off


*Only one encoder has been defined for Ingest and set to off.


13.Rename [encoder name] [new name] : Rename an encoder.

Rename "Encoder 1" "Encoder with 3 presets"

OK: Encoder has been renamed.


*The user should use double quotations, because of the spaces in encoder names.


14.Save [file name] : Saves project to a file.

Save qt.mi2prj
OK: Project saved.


*This command saves the project to the folder defined on the folder field of Output tab at Profiles window.


Save "C:\Program Files\Metus Technology\Metus Ingest 4.X\Projects\qt.mi2prj"

OK: Project saved.


*It saves the project to the Projects folder in Metus Ingest 3.2


15.Save :  Saves project.

Save

OK: Project saved.


* "Save"  command opens <Save As> box to save the project as a file with .mi2prj extension.


16.Setfile [encoder name] [profile index] [output file name] : Sets the output file name of a profile.

Setfile Encoder1 2 VCD_PAL

OK: New output file: D:\INGEST CAPTURE\VCD_PAL.mpg


*The folder path defined on the folder field of Profiles window is “D:\INGEST CAPTURE”, therefore the file “VCD_PAL.mpg” will be saved to this folder.


17.Setfile [encoder name] [output file name] : Sets the output file name of all profiles of an encoder.

Setfile Encoder1 Test_Presets

OK: All file names are updated.


*The file names of all profiles for Encoder1 have been set to Test_Presets.


18.Setfolder [encoder name] [profile index] [output folder name] : Sets the output folder of a profile.

Setfolder Encoder1 1 MPEG-2

OK: New output file: C:\Program Files\Metus Technology\Metus Ingest 4.X\MPEG-2\Test_Presets.mpg


*The first profile for Encoder1 has been located to the folder MPEG-2


19.Setfolder [encoder name] [output folder name] : Sets the output folder of all profiles of an encoder.

Setfolder TestEncoder1 Test3Presets

OK: All folders are updated.


*All profiles have been located to the folder Test3Presets.


20.Split :  Splits all encoders.

Split

OK: OK: Encoder 'TestEncoder1' has been splitted succesfully.


*The files for all encoders have been splitted during recording.


21.Split [encoder name] : Splits all profiles of an encoder.

Split TestEncoder1

OK: Encoder 'TestEncoder1' has been splitted succesfully.


*The files for the encoder TestEncoder1 have been splitted during recording.


22.Split [encoder name] [profile index] : Splits profiles.

Split TestEncoder1 3

OK: Profile has been splitted succesfully.


*The file for the third profile has been splitted during recording.

Note: If the Encoder Status of Profile is ES_Stopped, then the profile is started.


23.SplitAt [encoder name] [timecode (milliseconds)] [timecodeSourceType] Splits all profiles of an encoder at specified timecode. TC_Embedded = 1, TC_Exernal_LTC = 2. Encoder must be started "StartAt" command in order to use "SplitAt"

SplitAt TestEncoder1 78780000 2

OK: Encoder 'TestEncoder1 ' will be splitted at 21:53:00.00



24.Start [encoder name] [profile index] : Starts profiles.

Start TestEncoder1 2

OK: Profile has been started succesfully.


*The second profile for this encoder has been started with this command.

Note: If the Encoder Status of Profile is already ES_Runned, then the profile is splitted.


25.StartAt [encoder name] [timecode (milliseconds)] [timecodeSourceType] Starts all profiles of an encoder at specified timecode. TC_Embedded = 1, TC_Exernal_LTC = 2.

StartAt TestEncoder1 78720000 2

OK: Encoder 'TestEncoder1 ' will be started at 21:52:00.00


26.Start :  Starts all encoders.

Start

OK: OK: Encoder 'Encoder1' has been started succesfully.


27.Start [encoder name] : Starts all profiles of an encoder.

Start TestEncoder1

OK: Encoder 'TestEncoder1' has been started succesfully.


*All profiles of TestEncoder1 has been started.


28.Stop :  Stops all encoders.

Stop

OK: OK: Encoder 'Encoder1' has been stopped succesfully.


29.Stop [encoder name] [profile index] : Stops profiles.

Stop Encoder1 2

OK: Profile has been stopped succesfully.


*The second profile for Encoder1 has been stopped.


30.Stop [encoder name] :  Stops all profiles of an encoder.

Stop Encoder1

OK: Encoder 'Encoder1' has been stopped succesfully.


31.StopAt [encoder name] [timecode (milliseconds)] [timecodeSourceType] Stops all profiles of an encoder at specified timecode. TC_Embedded = 1, TC_Exernal_LTC = 2. Encoder must be started "StartAt" command in order to use "StopAt"

StopAt TestEncoder1 78840000 2

OK: Encoder 'TestEncoder1 ' will be stopped at 21:54:00.00


32.Stream [encoder name] [on/off] : Enables or disables source streaming for an encoder.

Stream “Encoder 1” on

OK:


*As it seen on the figure below, Stream command sets on Enable checkbox located at Encoder Settings menu. The user should also enter the Port Number from this menu box.


33.Stream [on/off] : Enables or disables streaming for all encoders.

Stream on

OK: Encoder Streaming is On


Stream off

OK: Encoder Streaming is Off


34.SysInfo :  Displays system status.

SysInfo

OK:

CPU Usage: 1%

Memory Usage: 31%

Disk Space:

C:\ has 42406 MBs of free space.

D:\ has 51572 MBs of free space.


*SysInfo informs the user for the system resources of the computer.

35.AddMarker [encoder name] [profile index] [marker type] [description]: Adds a marker to the selected profile. Marker type options are Regular, Marker In, Marker Out. (Note: It is case sensitive.)


AddMarker "Encoder 1" 1 Regular test

OK: Markers added successfully.

36.ClearMarkers [encoder name] [profile index]: Clears all markers from the selected profile.

ClearMarkers "Encoder 1" 1

OK: Markers cleared successfully.


             

37.SetStreamSource [encoder name] [stream address]: Changes NDI source

                    SetStreamSource "Enc" "Name: MYILMAZ2016 (NDI) IP: 10.7.10.27:5961"

                    OK: Encoder source has been set to 'Name: MYILMAZ2016 (NDI) IP: 10.7.10.27:5961'

38.SetTapeName [encoder name] [profile index] [new tape name value]

(Updates the Tape Name setting of a profile.)

SetTapeName "enc" 1 "Tape1"
OK: Tape name updated to 'Tape1'


39.SwitcherGetInputs [Switcher Name] [Preset Name]

The response may change based on the preset configuration.

Sample Command: SwitcherGetInputs Kramer myPreset1

Response 1: OK: Count:12 

Response 2: OK: Range: 3-8  

Response 3: OK: Selection:1,TV2;4,TV8


40.SwitcherGetOutputs [Switcher Name] [Preset Name]

The response may change based on the preset configuration.


Sample Command: SwitcherGetOutputs Kramer myPreset1

Response 1: OK: Count:8

Response 2: OK: Range: 3-8  

Response 3: OK: Selection:1,Studio;4,Recorder1


41.SwitcherTake [Switcher Name] [Preset Name] [Input No] [Output No]

The operation result on the switcher side is not checked. OK returns if the command is sent from the plugin without any error. 


Sample Command: SwitcherTake Kramer myPreset1 2 10


NOTE: Error response for all the cases starts with "FAILED: ..."

Switcher syntax names should be following;

Jupiter
Kramer
Pro-Bel
Quartz
Blackmagic


42.GrabFrame [encoder name]

(Grab frame from the encoder and returns Base64 String)


As a Summary, All commands are seen in the command prompt window below :