Key Concepts

Introduction

In order to gain a firm grasp on SAVE v1.2.x, and to be able to utilize the application to its maximum potential, there are a few key concepts that users should understand about the program's design philosophy. These are concepts that will remain relevant across minor and major version upgrades of the software, and will help you to form a coherent mental model of the program, allowing you to make educated guesses about how certain features can be used and extended to fit your needs.

Modules

All of SAVE's program features are neatly isolated into atomic, non-overlapping packages of functionality called Modules. Modules are intended to mirror the concept of individual analog video components of the old days, each of which served its own unique purpose while also enabling each other through physical cable connections carrying video signals.

With this analogy in mind, users can comfortably think of modules in SAVE as virtual, emulated versions of the physical, real machinery they imitate. Modules can be plugged into each other interchangeably and exist in parallel, and all of them have at least one input and output. Furthermore, SAVE uses modules to distinguish the boundary between the realms of digital video and analog video. Much like how HDMI cables can't be plugged into RCA ports on an old analog TV set, virtual digital outputs coming from SAVE modules must match with virtual digital inputs (and likewise with virtual analog outputs/inputs).

In SAVE, all modules only ever operate on either digital or analog video signals. The documentation for each specific module denotes this distinction as video standing for digital signals and signal standing for analog signals. These qualifiers are used together with a forward slash (/) to form an input/output pair.

As our final note on modules, we want to express that this concept can lead to powerful interoperability that has not yet been implemented into the application. For example, while SAVE only supports files as its main inputs and outputs at the moment, in the future it could support live digital OR analog video sources, either streaming in over the network or coming from a physical hardware connection. Modules allow for a subtle, but powerful separation of responsibilities within SAVE, and as a result represent a key design feature moving forward.

Job-strings

In SAVE, Job-strings are a more precise and concrete concept than Modules are. Effectively, job-strings are a sequence of textual characters that explicitly tell the application how to process its inputs and eventually return it as output. At a higher level, job-strings are a list of Modules with matching output/input pairs that transforms video data in a sequence. To format a job-string, first search for the path of the module you want to deploy (for example, v\cam\vidicon.simple for the simple vidicon tube camera emulator). Then write that path out. Optionally, to begin specifying parameters for the preceding module, follow its path with an = sign.

Examples: v\cam\vidicon.simple or v\cam\vidicon.simple=(rest of job-string)

Then, to specify each parameter, write its code-name (within this documentation, denoted inside the parenthesis after each parameter's full name) followed by another = sign. After the =, write the parameter's value (usually either an integer or number with a decimal point). To optionally start specifying the next parameter, follow the preceding parameter value with a : character, then repeat the process.

Examples: v\cam\vidicon.simple=r=3.0 or v\cam\vidicon.simple=r=3.0:g=3.0:b=3.0

After you are done specifying any, multiple, or all parameters for the given module, you can optionally add a , character to start specifying the next module. You may use as many modules in sequence with each other as you like, even repeating the same ones, so long as the previous one's output type matches the next one's input type.

Good examples: v\cbvs\ntsc.mod,v\cbvs\ntsc.scan,v\cbvs\ntsc.demod or v\cbvs\ntsc.mod,v\cbvs\ntsc.scan,v\cbvs\ntsc.demod,v\cbvs\ntsc.mod

Bad examples (non-matching output/input pairs): v\cam\vidicon.simple,v\cbvs\ntsc.demod or v\cbvs\ntsc.mod,v\cbvs\ntsc.mod

As a final step to creating your job-string, ensure that the output type of the final module matches with the extension of your output file path. signal type outputs should be written to .volta files and video type outputs should be written to .mp4 files. These are the only two file extensions that are accepted for output file paths at the command line as of SAVE v1.0.0.