Jobs Data

Contents

Introduction

A ROAD Job is a description of an audio processing task, which is to run at any time, but as a concluded process. It has a CurrentState describing if it's valid, waiting, running, finished, etc. Its state changes by Transitions which are part of the job's data and which may be added at any time. The DirectShow filter graph, which is need for actual audio processing is specified by the JobDescription, which is part of a Transition and which may be modified by later Transitions. A Transition is realized when its Trigger activates it.

A ROAD job can be expressed in JSON and be stored in a web page, database or file. It must be independent from specific machines and should be portable at least inside a company installation context. Job definitions could be used as universal descriptors to be used in any interfaces between components.

The job and its transitions may be incomplete (as long as the job isn't to be processed) and each data member of it may be updated at any time (maybe with restrictions while running).

Data Structure Diagram

Terms and Data Type Names

We omit any "ROAD" prefixes for all terms.

Data Fields

Jobs

A job which is to run (this applies to all real jobs, in difference to job templates) will have a history consisting of at least two so-called transitions (start and finish), but may have even more, depending on what's happening. Each transition contains exactly one so-called trigger, which defines when it is to occur and which new processing state is requested. A transition may contain a job description, which updates the actual input, output or mixer configuration.

Transitions

A job's Transitions field describes the past or planned Transitions the job ran or runs through while being processed. Each of them contains a specification of what and when to change and may contain a DirectShow pipe description for input and/or output side as well as a mixer specification for gain leveling and mixing matrix.

Triggers

Triggers describe when to go into a transition and which processing state is requested then.

A trigger leads into transition from one job state to another. One trigger can occur only once and is exhausted then.

Several triggers are elapsed in their sequence, if possible.

JobDescription

JobDescriptions describe how a job processing is specified after having gone into a transition.

JobDescriptions are differential, this means all former parts not mentioned later remain and only changing parts need to be specified. So the first transition may describe the DirectShow graphs needed to play a file and broadcast it via RTP and later transitions only contain leveling information.

See Job Description Data for more about JobDescriptions.

Processing States

We distinguish two job processing states - RequestedProcState and CurrentState - which are connected with each other as a change of requested state leads into an action in the processing, which mostly causes a change of its current state.

Requested ProcStates

Note: The described "follow-up current ProcState" state is the CurrentState, which will result from the requested one in the usual successful case. This may occur with some delay or even fail.

Current ProcStates

Note: The described "results from requested ProcState" is the RequestedState, which leads into the current one in a usual successful case. CurrentStates can of course change by other reasons, too (e.g. job finishes itself or runs into an error).

Timers

Timer-triggers jobs will be sent to worker with a Running RequestedState as the timer is associated with the requested state. The Worker then prepares the DS pipe and set the job's CurrentProcState to Waiting.

Pipe Specifications

A pipe specification consists of

• input queue(s)
• mixer connections and configuration
• output queue(s)

Not all these parts have to be provided in every case as ROAD supports partial updates and provides defaults for some cases.

Modifications on Running Jobs

Any change on a running job must be triggered. So a running job can only be modified by adding transitions which realize a changed job specification, e.g. a new gain value or a changed PipeSpec. (Later: or removing still pending transitions. Adding here could also mean to insert it at a specific location in the sequence.)

"Running job" means any job being at least in waiting state, so potentially being cared for by a Worker process.

Job Templates

Job templates contain a general part of a type of jobs. They are used to create a complete job by duplicating and completing or overriding some fields.

Job JSON Examples

Start Recording 

{  
  "jobId": "12345",
  "name": "Recording Test 123",
  "transitions": [  
    {  
      "trigger": {  
        "type": "Immediate",
        "requestedProcState": "Start"
      },
      "jobDescription": {  
        "pipeSpec": {  
          "InputGraph": [  
            { 
              "Name": "Input", 
              "Filter":[  
                {  
                  "Name": "ASIO Source",
                  "Device": {  
                    "Name": "ASIO Hammerfall DSP",
                    "Channels": "1, 2, 7"
                  },
                  "Format": {  
                    "SampleRate": "Sample44100",
                    "Resolution": "Res16Bit"
                  }
                }
              ]
            }
          ],
          "Mixer": {  
            "Comment": "the mixer will be configurable in a later step",
            "Matrix": {  
              "Comment": "define to connect input In1 with output Out1"
            }
          },
          "OutputGraph": [  
            {
                "Name": "Output",
                "Filter": [  
                {  
                  "Name": "WAVDest",
                  "Clsid": "{79376820-07D0-11CF-A24D-0020AFD79768}",
                  "Title": "This is a test BWF file",
                  "WriteRf64": true,
                  "WriteLevlChunk": true
                },
                {  
                  "Name": "FileWriter",
                  "Clsid": "{79376820-07D0-11CF-A24D-0020AFD79769}",
                  "Filepath": "\\\\fileserver1\\test\\file1.wav"
                }
              ],
              "Comment": "Currently the graphs are connected in a queue. Later this may become configurable."
            }
          ]
        }
      }
    }
  ]
}

Stop Recording 

{  
  "transitions": [  
    {  
      "trigger": {  
        "type": "Immediate",
        "requestedProcState": "Finish"
      }
    }
  ]
}

Implications

• A job always has at least one transition.
• A transition can be recognized as passed by its state (not invalid or pending) and timestamp (valid).
• Not every transition must be passed to finish a job.
• The current state of a job is always documented in the newest passed transition. But to access this information directly, there's the (redundant) CurrectState field of the job.
• The job's history is described by all passed transitions. As the trigger data remains, the "intended" flow remains documented (for passed and not passed transitions).
• The final transition may lead into a message text (+ friendly text) information, mostly used for errors.