-
Notifications
You must be signed in to change notification settings - Fork 15
Developer documentation: HTV save file format
This document outlines the structure of the HTV file format used by the Java version of hacktv-gui, and how it can be read.
The basic structure of the file follows the same conventions as an INI file. Settings which are specific to hacktv are saved in the [hacktv] section of the file. Earlier builds required this section to be at the top of the file but this is no longer a requirement as of 2021-08-24. Additionally, an optional [hacktv-gui3] section can be included, which specifies options specific to hacktv-gui. Finally, a playlist of file paths can be defined in an optional [playlist] section. The file can use either Windows style line breaks (CR + LF) or Unix-style line breaks (LF only).
This document is correct as of 17/07/2024. hacktv is in constant development so options may be added or removed at any time.
The option is listed in bold and the expected type of the value is listed in brackets beside it. These options can be specified in any order and it is not necessary to specify them all, except for those marked as mandatory. For Boolean values, a value of 0 (or if not defined) disables the option, while 1 enables the option. Text strings are not case sensitive unless specified otherwise.
output (text string)
Specifies the output device. This defaults to hackrf if omitted. Valid values are currently hackrf, soapysdr, fl2k or file. Device names or IDs can be added by suffixing the value with a colon - e.g. soapysdr:lime.
input (text string)
Specifies the input file or URL for hacktv to use. Specify test:colourbars to use the internal test pattern instead. Captain Jack’s fork also support other options, see its documentation for further details. This option can be omitted if using a playlist or Extended M3U file source.
mode (text string)
This option is mandatory. Specifies the video mode for hacktv to use. This can be any video format supported by hacktv – e.g. use i for PAL system I, or a for 405-line black and white. See hacktv’s documentation for the available options.
frequency (integer value)
Specifies the transmission frequency for the HackRF in Hz.
samplerate (integer value)
Specifies the sample rate in Hz. If omitted, this will default to 16 MHz.
gain (integer value)
Specifies the gain of the transmission in decibels. Must be between 0 and 47 dB as per hacktv’s documentation.
amp (Boolean value)
HackRF only. Enables or disables the transmission amplifier. 0 = amp disabled, 1 = amp enabled.
antenna (text string)
SoapySDR only. Specifies the antenna name.
filetype (text string)
File output only. Specifies the data type of the output file. See hacktv’s documentation for the available options.
level (double value)
Specifies the output level.
deviation (integer value)
Specifies the deviation for FM modes in Hz.
gamma (double value)
Overrides gamma correction.
repeat (Boolean value)
Repeats the input source indefinitely. 0 = repeat disabled, 1 = repeat enabled.
position (integer value)
Specifies the start position in minutes.
verbose (Boolean value)
Enable verbose output. 0 = no verbose output. 1 = verbose output.
logo (text string)
Embeds an on-screen logo. See Captain Jack’s hacktv’s documentation for the available options. Earlier versions of hacktv supported external PNG files but these are no longer supported.
timestamp (Boolean value)
Embeds an on-screen timestamp. 0 = no timestamp, 1 = show timestamp.
interlace (Boolean value)
0 = do not interlace, 1 = interlace.
teletext (text string)
Specifies the path of a teletext file or container. Containers (.t42 files) should have the prefix raw: (not case sensitive) added to the path.
wss (integer value)
Specifies the WSS mode to use. The following values are supported:
0 = no WSS
1 = auto
2 = 4:3
3 = 16:9
4 = 14:9 letterbox
5 = 16:9 letterbox
arcorrection (integer value)
Specifies how widescreen material should be presented on a 4:3 display. The following values are supported:
0 = Stretched (default)
1 = Letterboxed (--letterbox)
2 = Cropped (--pillarbox)
scramblingtype (text string)
Specifies the video scrambling system to be used. Leave blank for none. See hacktv’s documentation for the supported options. If VideoCrypt I and II are enabled together, this value should be set to videocrypt1+2 and the scramblingkey and scramblingkey2 values must also be specified.
scramblingkey (text string)
Specifies the conditional access key or card used by the scrambling system above. If VideoCrypt I and VideoCrypt II are enabled together, this specifies the conditional access key or card used by VideoCrypt I. This value must only be populated if the scramblingtype option is not blank. See hacktv’s documentation for the supported options.
scramblingkey2 (text string)
This value must only be populated if VideoCrypt I and VideoCrypt II are enabled together. It specifies the conditional access key/card used by VideoCrypt II.
emm (integer value)
Specifies whether EMM data is transmitted to switch on or off a viewing card. If this value is set to 1, or 2, a card number must be specified under the cardnumber value.
0 = no EMM data transmitted (default)
1 = Sends an enable command to the card (--enableemm option)
2 = Sends a disable command to the card (--disableemm option)
cardnumber (text string)
Specifies the viewing card number for the enableemm or disableemm options. This should be set to the 8 digits required by hacktv. This is a text string and not an integer because there could be a leading zero in a card number, but anything other than numeric values is invalid.
showserial (Boolean value)
0 = Do not show card serial on-screen. 1 = Show card serial on-screen.
findkey (Boolean value)
0 = Disabled. 1 = Brute force key search for PPV cards (e.g. phone cards).
scramble-audio (Boolean value)
Scrambles audio for supported modes. This setting should be used to handle both the --systeraudio and –scramble-audio options. 0 = disabled, 1 = audio scrambling enabled.
ec-mat-rating (integer value)
EuroCrypt M only. Specifies the maturity rating of the programme. 0 will disable it, or 1-15 will restrict the programme to the specified age. If parental controls are enabled on the access card, the decoder may prompt for a PIN to decode the programme.
ec-ppv (Boolean value)
Specifies if EuroCrypt pay-per-view (PPV) mode is enabled or not. 0 = disabled, 1 = enabled.
ec-ppv-num (integer value)
Specifies the programme number of the EuroCrypt PPV programme. This will default to 0 if not defined, and is ignored if ec-ppv is disabled or not defined.
ec-ppv-cost (integer value)
Specifies the cost of the EuroCrypt PPV programme. This will default to 0 if not defined, and is ignored if ec-ppv is disabled or not defined.
acp (Boolean value)
Specifies if analogue copy protection (aka Macrovision) is enabled or not. 0 = disabled, 1 = enabled.
filter (Boolean value)
Specifies if the VSB-AM or FM pre-emphasis filter is enabled or not. 0 = disabled, 1 = enabled.
showecm (Boolean value)
Specifies if ECMs are shown on the console or not. 0 = disabled, 1 = enabled.
subtitles (Boolean value)
Specifies if subtitles are enabled or not. 0 = disabled, 1 = enabled.
subtitleindex (integer value)
Specifies the index value of the subtitle stream in the video file or SRT file.
audio (Boolean value)
Specifies if audio is enabled or not. 0 = disabled, 1 = enabled.
nicam (Boolean value)
Specifies if NICAM stereo is enabled or not. 0 = disabled, 1 = enabled. This setting must not be enabled if a2stereo is also enabled.
a2stereo (Boolean value)
Specifies if A2/Zweikanalton stereo is enabled or not. 0 = disabled, 1 = enabled. This setting must not be enabled if nicam is also enabled.
vits (Boolean value)
Specifies if the VITS test signal is enabled or not. 0 = disabled, 1 = enabled.
vitc (Boolean value)
Enables or disables VITC support. 0 = disabled, 1 = enabled.
chid (text string)
Specifies the channel ID used by a MAC service. Hexadecimal values are allowed.
mac-audio-mode (text string)
Specifies stereo or mono audio for MAC modes. A value of mono will force mono audio. If this is not defined, or set to any other value, stereo audio is produced.
mac-audio-quality (text string)
Specifies 32 kHz (high quality) or 16 kHz (medium quality) audio for MAC modes. A value of medium will set the sample rate to 16 kHz. If this is not defined, or set to any other value, the sample rate defaults to 32 kHz.
mac-audio-compression (text string)
Specifies audio compression for MAC modes. A value of linear will output linear audio (rather than companded). If this is not defined, or set to any other value, companding is used.
mac-audio-protection (text string)
Specifies the audio protection level for MAC modes. A value of l2 (the letter 'L' as opposed to 'I') will use level 2 protection. If this is not defined, or set to any other value, level 1 protection is used.
nocolour or nocolor (Boolean value)
Disables the colour subcarrier on supported modes. Accepts either UK or US English spelling but UK English takes precedence. 0 = colour enabled, 1 = colour disabled.
invert-video (Boolean value)
Inverts the sync and white levels, so negatively modulated modes become positively modulated and vice versa.
volume (double value)
Adjusts the volume of the output.
downmix (Boolean value)
Downmixes 5.1 audio to 2.0 (stereo). 0 = disabled, 1 = enabled.
tx-subtitles (Boolean value)
Enables teletext subtitles on page 888. 0 = disabled, 1 = enabled.
Note: Previous versions of hacktv-gui used teletextsubtitles instead. This was changed in the 2021-08-24 build to match the argument used by hacktv. Either setting is accepted but tx-subtitles takes precedence.
tx-subindex (integer value)
Specifies the index value of the subtitle stream in the video file or SRT file for teletext subtitles.
Note: Previous versions of hacktv-gui used teletextsubindex instead. This was changed in the 2021-08-24 build. Either setting is accepted but tx-subindex takes precedence.
pixelrate (integer value)
Specifies the pixel rate of the video. If not specified, the pixel rate is set to the sample rate.
sis (integer value)
Enables the Sound-In-Syncs option.
sismode (text string)
Specifies the Sound-In-Syncs mode. This setting is currently ignored because dcsis is the only option supported by hacktv. If additional SiS modes are added in future, this setting will become active and will control a combobox.
The following options are used specifically by hacktv-gui.
fork (text string)
Specifies the hacktv fork (if any) that the file targets. Omission of this setting will be treated as fsphil’s original build. This is used internally by hacktv-gui to present the correct options for that fork. At this time, captainjack is the only supported value.
m3usource (text string)
Specifies the path to an M3U playlist file. If this is defined, the source setting in the hacktv section is ignored and this is processed instead.
m3uindex (integer value)
If an M3U playlist file is in use, this specifies the location of the selected item in the dropdown combo box. 0 is the first item in the combo box, 1 is the second… and so on.
channel (text string)
This specifies the channel number selected in the hacktv-gui interface. If this is specified, it will override the frequency used in the hacktv section. For example, specifying this value as E36 on video modes B/G or I will set the frequency to 591.25 MHz. Invalid values will return an error; this must be written exactly as presented in the GUI but is not case sensitive.
bandplan (text string)
This specifies the band plan (region) that was selected in the region dropdown on the Output tab. The value of the setting is the section name in Modes.ini that corresponds with the selected item.
13digitprefix (text string)
This option has been deprecated as of the 2024-11-19 release. New save files won't use it, but existing files will still be read.
hacktv only requires digits 5-12 but hacktv-gui shows the full card number for cosmetic purposes. If a 13-digit card number was specified, this specified the first four digits of the card. It calculated the last digit (the check digit) based on digits 5-12 using the Luhn algorithm.
playlist (Boolean value)
Setting this value to 1 will instruct hacktv-gui to use the playlist specified in the [playlist] section. In this case, the source value in the [hacktv] section is ignored and this is processed instead.
playliststart (integer value)
Specifies the entry in the playlist that is to be used as the start point. Must be an integer value of 1 or greater. For example, setting this to 5 on a 7-line playlist will play the files in the order 5, 6, 7, 1, 2, 3, 4.
random (Boolean value)
Randomises (shuffles) the playlist at runtime. The entry at playliststart (if specified) will play first, and the rest will be played at random. Test cards are ignored if this value is set to 1.
The playlist section does not follow a standard INI ‘setting=value’ format. It’s simply a list of file paths separated by line breaks (LF or CR+LF). In order to use this, the playlist setting in the [hacktv-gui3] section should be set to 1. A sample file is shown at the end of this document.
It’s possible to add a test card to the playlist. It should be added as the last entry because the test card runs indefinitely. As a result, anything specified after the test card would never be played.
Below is a sample file created in hacktv-gui version 3.0.
[hacktv] source=http://example.com/test.ts mode=i frequency=687250000 samplerate=14000000 gain=20 logo=cartoonnetwork arcorrection=1 scramblingtype=videocrypt scramblingkey=sky09 audio=1 nicam=1 [hacktv-gui3] fork=captainjack channel=E48
This generates the following syntax for hacktv:
-m i -f 687250000 -s 14000000 -g 20 --videocrypt sky09 --logo cartoonnetwork.png --letterbox http://example.com/test.ts
Below is a sample file created in hacktv-gui release 2021-08-24 with the playlist option enabled.
[hacktv] output=hackrf mode=i frequency=687250000 samplerate=16000000 pixelrate=28000000 gain=20 logo=hacktv arcorrection=1 scramblingtype=videocrypt scramblingkey=sky09 audio=1 nicam=1 [hacktv-gui3] fork=CaptainJack playlist=1 channel=E48 [playlist] D:\videos\video1.mpg D:\videos\video2.mp4 C:\Users\User\Desktop\video3.mp4 test:colourbars
This generates the following syntax for hacktv:
-m i -f 687250000 -s 16000000 --pixelrate 28000000 -g 20 --videocrypt sky09 --logo hacktv --letterbox D:\videos\video1.mpg D:\videos\video2.mp4 C:\Users\User\Desktop\video3.mp4 test:colourbars