JSON Metadata format

Purpose

The ld-decode project is made up of a series of tools which form a processing tool-chain for capturing, processing, analysing and combining LaserDisc 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 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 tool-chain.

Conventions

Supported JSON data types

Name	Qt Equivalent	Description
String	QString	String of UTF-8 characters
Number	qint32 or qreal	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 producing a .tbc file will also produce a .tbc.json file containing the 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 and sequential field numbers start from 1. Scan-lines and field-lines start from 1 (i.e. a PAL decode contains scan-lines 1 to 625 and NTSC 1 to 525). In both cases 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
isSourcePal	Boolean	true = source is PAL, false = source is NTSC
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
samplesPerUs	Real number	The number of pixel samples per uS of time
fieldWidth	Integer	The width of each field in pixels
fieldHeight	Integer	The height of each field in scan-lines
sampleRate	Integer	The sample rate in Hz (17734476 for ld-decode)
fsc	Integer	The Fsc in Hz (4433619 for PAL, 3579545 for NTSC)

Note: 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).

pcmAudioParameters

Name	Type	Description
sampleRate	Integer	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
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
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 phase of the first field line (currently NTSC only)
audioSamples	Integer	The number of audio samples corresponding to the video 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

Note: This object is preliminary, and may still change.

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	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 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
ccData0	Number (integer)	The first closed caption byte (if available)
ccData1	Number (integer)	The second closed caption byte (if available)

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

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