Skip to content

JSON Metadata format

Harry Munday edited this page Mar 21, 2024 · 119 revisions

Purpose

The decode projects are made up of a series of decoders and tools which form a processing tool-chain for processing, analysing decoded RF samples. In order for each tool in the chain to communicate in an efficient manner a JSON metadata file is used to store and communicate information about the decoded RF capture and any data that has been determined.

Tools should (as appropriate) be able to accept metadata as well as output metadata.

This document describes the metadata format to be used by all tools in the decode tool-chain.

Conventions

Supported JSON data types

Name Qt Equivalent Description
String QString String of UTF-8 characters
Number qint32 or double Integer or real number
JSON object Object Object
Array Vector Vector of another type
Boolean Qbool Boolean value of true or false

File names

When producing a JSON metadata file the application/utility will use its normal file extension with .json added. For example, ld-decode & cvbs-decode produces a .tbc file containing the composite signal, and a .tbc.json file containing the metadata. (For colour-under formats, vhs-decode additionally produces a file with the suffix _chroma.tbc containing the chroma signal; this can be processed using the same .tbc.json metadata.)

All metadata should be considered as optional. Each tool will add metadata as appropriate but should be able to handle the case when metadata is not available.

Invalid data fields

A field with a null or -1 value (for integers) should be considered as invalid.

Object numbering

VBI frame numbers, sequential field numbers and field-lines are numbered starting from 1. A value of 0 should be considered as invalid.

Objects

metaData

Name Type
videoParameters Object videoParameters
pcmAudioParameters Object pcmAudioParameters
fields Array field

videoParameters

Name Type Description
numberOfSequentialFields Integer The total number of fields decoded
system String The video system in use: "PAL", "NTSC", "PAL-M"
colourBurstStart Integer Position (in pixels) of the colour-burst start
colourBurstEnd Integer Position (in pixels) of the colour-burst end
blackLevelStart Integer Position (in pixels) of the black-level start
blackLevelEnd Integer Position (in pixels) of the black-level end
activeVideoStart Integer Position (in pixels) of the start of the active video line
activeVideoEnd Integer Position (in pixels) of the end of the active video line
white16bIre Integer The white level IRE in a 16-bit scale
black16bIre Integer The black level IRE in a 16-bit scale
fieldWidth Integer The width of each field in pixels
fieldHeight Integer The height of each field in field-lines
sampleRate Double The sample rate in Hz (usually 4 * fSC for ld-decode)
tapeFormat String The type of tape media format i.g VHS, Betamax, Video8
isMapped Boolean true if the video has been mapped by ld-discmap
isSubcarrierLocked Boolean true if samples are subcarrier-locked
isWidescreen Boolean true if the video is 16:9 anamorphic, rather than 4:3
gitBranch String The git branch ID of ld-decode used to decode the TBC
gitCommit String The git commit ID of ld-decode used to decode the TBC

Notes:

A video system is a combination of a line standard and a colour standard - see World TV Standards. "PAL" is standard 625-line PAL, and "NTSC" is standard 525-line NTSC; these are the only two systems used on LaserDisc. "PAL-M" is the 525-line PAL system used in Brazil, and is supported by vhs-decode. Other systems may be supported in the future.

The 'blackLevelStart' and 'blackLevelEnd' parameters point to a recommended section of the scan-line from which the average black level IRE can be determined. This is typically from the end of the colour-burst (with some safety margin) to the beginning of the active video (again with some safety margin).

fieldHeight represents the taller of the two video fields. In the .tbc file, the shorter field will be padded with an additional line at the end to make both fields the same size. The first field is always the taller of the two - that is, in 625-line systems, the whole of line 313 is considered to be part of the first field, not the second (which is not always the convention used elsewhere).

isSubcarrierLocked indicates, for video sampling rates where there are not an integer number of samples in each line of video, whether the samples are aligned to the start of lines (line-locked) or to the colour subcarrier (subcarrier-locked). For subcarrier-locked sampling, any additional samples at the end of the frame can be found at the start of the second field's padding line. PAL digital video is often subcarrier-locked with a sample rate of 4fSC, giving four extra samples after the end of the second field; for NTSC, there are an integer number of 4fSC samples in a line so it doesn't make a difference.

pcmAudioParameters

Name Type Description
sampleRate Double The sample rate in Hz
isLittleEndian Boolean true = sample is little endian, false = sample is big endian
isSigned Boolean true = sample data is signed, false = sample data is unsigned
bits Integer The number of bits used per sample (i.e. 16)

field

Name Type Description
seqNo Integer The unique sequential field number for the field
diskLoc Integer The location in the file (in fields) the field is located
fileLoc Integer The sample # in the file the field is located
isFirstField Boolean true = first field, false = second field
syncConf Integer 0 = poor, 100 = perfect - The percentage confidence of the sync point determination
vits Object vits The VITS information
vbi Object vbi The VBI information
ntsc Object ntsc NTSC specific information
vitc Object vitc Vertical Interval Timecode (if present)
dropOuts Object dropOuts The detected RF drop-outs in the field
medianBurstIRE Real number The median point of the colour burst (in IRE)
fieldPhaseID Integer The position of this field in the 4 (NTSC) or 8 (PAL) field sequence
audioSamples Integer The number of (stereo, signed 16-bit) audio samples corresponding to the video field
efmTValues Integer The number of .efm T-Values (in bytes) corresponding to the video field
decodeFaults Integer bit 1: first-field detection failure, bit 2: field phase ID mismatch, bit 3: skipped field (likely a player skip)
pad Boolean true = field is padded (contains no valid video data), false = normal field

vitsMetrics

The VITS object contains data obtained by analysing the VITS field lines. Not all data is available in all fields (i.e. white* on NTSC)

Default:

Name Type Description
wSNR real number The Signal to Noise ratio of a white (100IRE) area of the field
bPSNR real number Black line PSNR (not conventional SNR)

Additional fields With --verboseVITS:

Name Type Description
whiteIRE real number The IRE level of the white sample, compared to the standard
whiteRFLevel real number The RF level of the white sample
greyPSNR real number The Peak Signal to Noise ratio of a grey (50IRE) area of the field
greyIRE real number The IRE level of the grey sample, compared to the standard
greyRFLevel real number NTSC ONLY: The RF level of the grey sample
blackLinePreTBCIRE real number Black line IRE, before TBC/wow-flutter correction
blackLinePostTBCIRE real number Black line IRE, after TBC/wow-flutter correction
blackLineRFLevel real number The RF level of the black line sample
syncLevelPSNR real number Sync sample PSNR (not conventional SNR)
syncRFLevel real number The RF level of the sync sample
syncToBlackRFRatio real number Ratio between sync and black RF signal level
syncToWhiteRFRatio real number Ratio between sync and white RF signal level
blackToWhiteRFRatio real number Ratio between black and white RF signal level
ntscWhiteFlagSNR real number The Signal to Noise ratio of the white flag, if it exists in this field
ntscWhiteFlagRFLevel real number The RF level of the white flag, if it exists in this field
ntscLine19Burst0IRE real number NTSC Line 19 Color burst level after TBC/scaling
ntscLine19Burst70IRE real number NTSC Line 19 70IRE burst level
ntscLine19ColorPhase real number The field X color phase
ntscLine19ColorRawSNR real number The field X raw SNR. This is unfiltered and should be lower than any post-processing chroma SNR, since it is ~3.59Mhz and on-disk chroma is never above 2Mhz.
ntscLine19Color3DPhase real number The "3D comb filtered" color phase (second field only)
ntscLine19Color3DRawSNR real number The "3D comb filtered" raw SNR (second field only). This is higher than the per-field values, but still should be below real-world chroma SNR.
palVITSBurst50Level real number PAL VITS 50IRE color burst level
cavFrameNr Integer CAV Frame # in VITS (useful for determining pulldown)
clvMinutes Integer CLV Minute # from VITS
clvSeconds Integer CLV Seconds # from VITS (not on early disks)
clvFrameNr Integer Computed CLV Frame # from VITS (if clvSeconds is present)

Note

This object is preliminary, and is subject to change as features are implemented within the decoders or vbi-processing tool or newer tools.

vbi

Note

See IEC 60857-1986 and IEC 60856-1986 for details.

Note

See IEC 60857-1986 Amendment 2 and IEC 60856-1986 Amendment 2 for details.

Name Type Description
vbiData Integer Array The field line 16, 17 and 18 raw VBI data (as 3 elements)
vp Array Array containing the VBI parameters (see below

Note

For ld-decode rev6 'vp' is removed and only vbiData is contained in the JSON.

The vp array contains the following values:

Element Type Description
0 Enum discTypes (integer) The disc type (CAV or CLV)
1 String The reported user-code for the field
2 Integer The picture number
3 Integer The chapter number
4 Number (integer) CLV programme time code hours
5 Number (integer) CLV programme time code seconds
6 Number (integer) CLV Current seconds value
7 Number (integer) CLV Current frame number (1-25 for PAL, 1-30 for NTSC)
8 Enum – Programme status - soundModes (integer) Current sound mode
9 Enum – soundModes (integer) Am2 Current sound mode
10 Integer 12-bit word of boolean flags (see below)

Flags (bit 0 is LSB):

bit Name Description
0 leadIn true = field is lead-in
1 leadOut true = field is lead-out
2 picStop true = field has stop-code set
3 cx Programme status - true = CX is on
4 size Programme status - true = disc is 12", false = disc is 8"
5 side Programme status - true = side 1, false = side 2
6 teletext Programme status - true = teletext data is present on the disc
7 dump Programme status - true = programme dump - See IEC specification
8 fm Programme status - true = FM-FM Multiplex - See IEC specification
9 digital Programme status - true = Video contents are digital - See IEC specification
10 parity Programme status - true = parity confirmed as correct, false = parity not confirmed
11 copyAm2 true = copying is allowed - See IEC Am2 specification
12 standardAm2 Am2 true = video signal is standard, false = future use

ntsc

Note: This object contains the field data that is specific to NTSC (and not present in the PAL IEC specifications)

Name Type Description
isFmCodeDataValid Boolean true = FM code data is valid, false = FM code data is invalid
fmCodeData Number (integer) The 20-bit FM code data payload (X5 to X1)
fieldFlag Boolean true = first video field, false = not first video field
whiteFlag Boolean true = white flag, false = white flag not present
isVideoIdDataValid Boolean true = VIDEO ID data is valid, false = VIDEO ID data is invalid
videoIdData Number (integer) The 14-bit VIDEO ID code data payload (IEC 61880)

cc

This object represents Closed Caption data for a field.

Name Type Description
ccData0 Number (integer) The first closed caption byte
ccData1 Number (integer) The second closed caption byte

For ccData0 and ccData1, if the value is -1 or not present then no valid CC was found. 0 is a valid value - it means that CC is present, but no data is being transferred on this line.

Note: See ANSI/CTA-608 for details.

vitc

This object represents Vertical Interval Timecode data for a field.

Name Type Description
vitcData Integer Array VITC raw data as 8 values

Each of the values in vitcData represents 8 bits of the raw VITC data, without the framing bits or CRC. The LSB of vitcData[0] is VITC bit 2 (the LSB of the frame number), and the MSB of vitcData[7] is VITC bit 79.

dropOuts

Name Type Description
startx Integer Array An array of start pixels for the detected drop-outs
endx Integer Array An array of end pixels for the detected drop-outs
fieldLine Integer Array An array of field-lines on which the drop-outs occur

Enums

VBI Disc types

This describes types of LaserDisc.

discTypes number (32-bit integer)

Name Value
unknownDiscType 0
clv 1
cav 2

VBI Sound Modes

soundModes number (32-bit integer)

Note

See IEC 60857-1986 and IEC 60856-1986 for details.

Name Value
stereo 0
mono 1
audioSubCarriersOff 2
bilingual 3
stereo_stereo 4
stereo_bilingual 5
crossChannelStereo 6
bilingual_bilingual 7
mono_dump 8
stereo_dump 9
bilingual_dump 10
futureUse 11

Page End

Clone this wiki locally