-
Notifications
You must be signed in to change notification settings - Fork 15
Developer documentation: Modes.ini file format
This document outlines the format of the Modes.ini file used by hacktv-gui.
Modes.ini was introduced in release 2021-08-02. This file contains all of the video modes, scrambling systems, logos, test cards, and channel band plans. Previously, these values were hard-coded into the Java binaries and couldn’t be edited without recompiling from source. From the 2024-10-30 release, the file was split in two for ease of maintenance, named fsphil.ini or captainjack.ini, and bandplans.ini. The latter (as the name suggests) contains the band plans while the former contains everything else, depending on the hacktv build in use.
There are three possible sources of the Modes.ini file:
-
External, in the same directory as hacktv-gui.jar
-
Online, from (depending on the build/fork in use):
or
and
-
Internal, inside the hacktv-gui.jar file at:
com/steeviebops/resources/fsphil.ini or com/steeviebops/resources/captainjack.ini
and
com/steeviebops/resources/bandplans.ini
hacktv-gui will check for the files in the order above. If the “Always use local copy of modes files” option is enabled on the GUI settings tab, the online files are skipped. This will also disable the prompt if an external file is detected. You can determine the location of the file that is currently in use by opening the About box from the Help option.
- The file itself is in a standard INI format, with ‘[sections]’ that contain ‘setting=value’ options.
- Most characters should be allowed in settings, with the exception of the backslash, square brackets, semicolon or the equals symbol. Values can contain anything except a semicolon, which is treated as the start of a comment. Use of special characters in section names, with the exception of the dash or underscore, should be avoided as this is untested.
- Comments are allowed on their own lines or in-line with values or section names. They'll be stripped out before processing.
- The only mandatory sections are [videomodes] and at least one mode section defined by it. All other sections are optional.
This document outlines the sections and their supported options. Section names are displayed in their square brackets. Values in bold are settings, while those in bold italics are possible values for those settings.
FileVersion (text string)
This is for information only and is displayed in the About box of hacktv-gui. This setting is optional, however, 2024-10-30 and later will use this to determine if the file is of the older, combined format (4.x or earlier), or the new split format without band plans (5.0 and later).
The [videomodes] section contains the section names of video modes that should be populated. For example, pal-fm will jump to the [pal-fm] section to read its settings.
Five settings can be specified here: pal, ntsc, secam, mac, and other. Omission of any of these settings will result in the radio button for that system being greyed out. Omission of all of these settings, and/or the section itself, will cause the application to exit. Separate the values by a comma; you can also use white spaces for clarity. An example is shown below.
[videomodes] pal=i, g, pal-fm, pal-m, pal, 525pal ntsc=m, ntsc-fm, ntsc-bs, apollo-fsc-fm, m-cbs405, ntsc, cbs405 secam=l, d, secam-fm, secam-i, secam other=a, e, 240-am, 30-am, apollo-fm, nbtv-am, 405, 819, 240, 30, apollo, nbtv mac=d2mac-fm, dmac-fm, d2mac-am, dmac-am, d2mac, dmac
These sections contain video scrambling keys for the system mentioned in the section name. The setting name is the key that will be passed to hacktv, while the value is a friendly name used in the GUI drop-down menus.
Some systems don’t send any parameter to hacktv. Examples include the Syster mode in fsphil’s build, and MAC when no CA (soft scrambling) is in use. Since “=free” isn’t a valid setting in an INI file (and would play havoc with anything trying to read it!) we use the word blank as a placeholder. If this is found, the specified setting is passed to hacktv without any parameter.
Omission of any of these sections will result in that system not being displayed in the drop-down menu. If all systems are omitted, the entire Scrambling tab will be disabled and greyed out. In releases prior to 2023-01-20, omission of any of these sections would trigger an error message if the missing scrambling system was selected, but no harm was done.
An example of this section is shown below.
[eurocrypt] blank=No conditional access (free) filmnet=EuroCrypt M (FilmNet card) tv1000=EuroCrypt M (TV1000 card) ctv=EuroCrypt M (CTV card) tvplus=EuroCrypt M (TV Plus card)
This section contains a list of settings used by the --logo parameter in Captain Jack’s fork of hacktv. It is ignored if using fsphil’s build. As with the scrambling systems mentioned above, the setting name is the key that will be passed to hacktv, while the value is a friendly name used in the GUI drop-down menus. An example is shown below.
[logos] hacktv=hacktv cartoonnetwork=Cartoon Network tv1000=TV1000 filmnet1=FilmNet1 canal+=Canal+
This section contains a list of 625-line test cards used by Captain Jack’s fork of hacktv. It is ignored if using fsphil’s build, which only supports colour bars at present. As with some other sections mentioned above, the setting name is the key that will be passed to hacktv, while the value is a friendly name used in the GUI drop-down menus. The test: prefix is appended automatically and should not be entered in the setting name. An example is shown below.
[testcards] colourbars=Colour bars pm5544=Philips PM5544 pm5644=Philips PM5644 ueitm=UEIT (Soviet) fubk=FuBK
As of 2022-11-21, hacktv-gui now supports the ability to use test cards for any line count. This is possible by appending the line count to the section name, for example, [testcards525] will define a list of 525-line cards. This is, of course, dependent on your copy of hacktv supporting them but it's here if you need it!
The video modes defined in the [videomodes] section have a set of parameters that define which settings should be enabled or disabled in the GUI, depending on what it supports. Below is a list of the supported settings.
alt (text string)
Optional value. This specifies an alternative identifier for this mode. For example, if defining PAL-B/G, you may want to set the section name as [b], while setting this to g or vice versa. This has no real purpose at present, except to allow either option to be accepted when hand-crafting HTV files.
name (text string)
This is a friendly name used in the GUI drop-down menu. Omission of this setting will result in the mode’s parameter being displayed, so it’s highly recommended to specify this from a user experience standpoint.
lines (integer)
Specifies the analogue line count of the video mode. At present, this is used to disable settings not supported in 625-line modes, as well as defining what rasterised test cards are available to the mode. This will default to 525 if not defined.
modulation (text string)
Supported values are vsb, fm or baseband. This allows other features in the GUI to be enabled or disabled based on what the modulation requires. For example, specifying fm will enable the FM deviation and pre-emphasis filter options, while specifying baseband will disable all RF options. This will default to vsb (AM) if not defined.
sr (integer)
Specifies the default sample rate for the specified mode in Hertz. This will default to 16000000 Hz (16 MHz) if not defined.
uhf and vhf (text string)
Specifies the section which contains the UHF and/or VHF band plans for this mode. The specified section will be parsed and its contents populated into the RF Options frame on the Output tab. Setting this value to 0, or not defining it, will disable the radio button for that band.
For the values listed below, setting to 1 will enable the option; while 0, or not defined, will disable it.
colour
Specifies if the “disable colour” (--nocolour) setting is supported
audio
Specifies if the audio options are supported
nicam
Specifies if NICAM stereo is supported
a2stereo
Specifies if A2/Zweikanalton stereo is supported
teletext
Specifies if teletext is supported
wss
Specifies if widescreen signalling is supported
vits
Specifies if VITS test signals are supported
acp
Specifies if ACP (Macrovision) is supported
scrambling
Specifies if video scrambling is supported
Each video mode can define up to five UHF and VHF band plans to use in the GUI. These settings are optional but can be provided for convenience. The name of the sections in bandplans.ini (or Modes.ini if the file format is version 4.x or earlier) should be specified under a uhf or vhf setting in the mode’s section. Additional sections can be defined by the settings uhf2 to uhf5, and vhf2 to vhf5.
2024-10-30 introduced a new way of handling satellite band plans. The previous method was to save the converted intermediate frequencies (IFs) as a region in Modes.ini. However this became more complex when the plan was then duplicated to include harmonic frequencies. In response to this, the new format was designed. Instead of defining the band plan as a UHF plan, the new sat option is used instead. Internally, this is still the UHF setting, but with special handling. The frequencies stored in the band plan should be the true satellite frequencies rather than the IFs. hacktv-gui will then calculate the correct frequency to send to hacktv, based on the settings defined under the "Satellite receiver settings" page. Like with the other options, additional plans can be added using the values sat2 to sat5.
In releases prior to 2024-10-30, the band plans were contained at the bottom of Modes.ini. From then on, they are now contained in a new file called bandplans.ini. The format is largely unchanged, except for how satellite frequencies are defined.
Releases before 2022-10-19 will only read the uhf and vhf settings; the others will be ignored. Releases before 2023-01-15 only support frequencies up to 2,147,483,647 Hz (2.147 GHz) due to a bug and will not process a band plan with a frequency higher than this.
There are three settings supported in these sections.
region (text string)
Specifies a text description of the band plan that is shown in the RF Options frame on the Output tab. Omission of this setting will result in the section name being displayed, so it’s highly recommended to populate this.
chid (text string)
Specifies the name of a section that contains MAC channel IDs for this mode. This is only supported on MAC modes and will be ignored otherwise. This setting is optional.
lo (long value)
Specifies the local oscillator frequency (in Hertz) of LNBs designed to receive this band plan. This setting will override the user-defined setting if the reception device is set to "Direct (IF)". This was primarily introduced to help calculate the correct IF for BSB receivers, so should be used in cases where the receiver has a fixed channel plan and cannot be retuned.
Anything else in this section (except comments) will be interpreted as follows.
- The setting name will be populated into the GUI as a friendly name in the GUI drop-down menu. Try not to exceed 14 or 15 characters as there’s not a lot of space available on-screen.
- The value of the setting is the frequency in Hertz, which is fed to hacktv.
An example of a VHF section is included below:
[vhf_eu] region=Continental Europe E2=48250000 E3=55250000 E4=62250000 E5=175250000 E6=182250000 E7=189250000 E8=196250000 E9=203250000 E10=210250000 E11=217250000 E12=224250000
MAC video modes can contain a hexadecimal channel ID value which can be used by the receiver’s firmware to identify the channel and display its name on-screen. The name of the section can be specified using the chid setting in the band plan.
The setting name needs to exactly match the setting name used in the band plan. The value must be a 4-character hexadecimal value, which is not case-sensitive. See example below.
[bsb_id] 4 (Now)=00B1 8 (Galaxy)=00B2 12 (Sports Ch)=00B3 16 (Power St)=00B4 20 (Movie Ch)=00B5