The interface
The main window is divided into tabs. The available options will depend on the build and fork of hacktv that is in use. Click a link below to skip to that section.
Source tab and playlist options
Mode tab
Output tab
Scrambling tab
GUI Settings tab
Satellite receiver settings button
Console output pane
Menu bar
On the Source tab, you can specify files to add to a playlist. Use a video file on your computer, or an internet stream from HTTP or HTTPS as the video source. RTMP streams may also work but I have not tested this. Any format supported by ffmpeg should work. Simple M3U files are supported and will populate the playlist with their contents. Extended M3U files are also supported; the file text box becomes a drop-down menu which will display each item in the file.
Selecting the Test card radio button will generate a colour bar test card as the video source. It also generates a 1 kHz stereo test tone to the GLITS specification, as was used on BBC One in the 1990s. Captain Jack's fork supports other test card designs when using a 625-line video mode, such as the 4:3 and 16:9 Philips patterns (commonly known as PM5544 and PM5644) and the Telefunken FuBK. These can be selected from the drop-down menu to the right of the radio button.
hacktv-gui also has basic support for yt-dlp (youtube-dl is no longer supported as of the 2023-01-05 release). If a YouTube URL is entered, you will be prompted to use yt-dlp to stream the video. If you want to use another streaming website that is supported by yt-dlp, you can force it by prefixing the URL with ytdl:. For example, to stream a video from Dailymotion, use ytdl:https://www.dailymotion.com/video/x88ss1. You'll then be prompted to use yt-dlp to stream the video as normal.
You can populate the playlist by using the Add button to select one or more files. You can also use a standard M3U file (a simple list of file paths). Use the up or down buttons to sort the playlist to your preference.
The Play first button will use the selected file as the start point in the playlist. For example, if you have 5 files in the playlist and you select the 4th file, this will cause the playlist to play in the order of 4, 5, 1, 2, 3.
Randomise playlist does exactly what it says. The playlist will be shuffled when the Run hacktv button is pressed.
Repeat indefinitely will repeat the selected file or playlist in an endless loop until hacktv is stopped.
Interlaced video updates the image on each field instead of each frame. Use this for progressive (50p/60p) material.
Overlay timestamp will overlay a timecode in the bottom left of the screen.
Subtitles will display on-screen subtitles if supported. This can be internal to the video or in a separate SRT file. If the video contains multiple subtitle streams, you can specify the index number of the stream you would like to use. The index numbers can be found in hacktv's output while it is running.
Start position will start the video file at the specified position. For example, specifying 10 will start playback at the 10 minute mark.
Overlay logo will overlay an on-screen logo (also known as a DOG or bug). Select the logo from the dropdown menu.
Aspect ratio scaling specifies how widescreen video files will be displayed on a standard 4:3 screen:
For fsphil's build, the following options are available:
- Stretched will stretch the 16:9 image to fit the screen (default).
- Fit will add black bars to the 16:9 image to preserve the aspect ratio.
- Fill will centre the 16:9 image on the full screen. This will display the centre portion of the 16:9 image in the correct aspect ratio, at the expense of losing the left and right sides of the image.
- None performs no scaling. You will most likely see an image that has black bars all around, or an image that is zoomed in with missing information on all sides.
For Captain Jack's build, the following options are available:
- Stretched will stretch the 16:9 image to fit the screen (default).
- Letterboxed will add black bars to the 16:9 image to preserve the aspect ratio.
- Cropped will centre the 16:9 image on the full screen. This will display the centre portion of the 16:9 image in the correct aspect ratio, at the expense of losing the left and right sides of the image.
Here, you can specify the video mode that you want to output with. See the Video Modes page for more details on the available options.
Deselecting the Audio enabled option will disable the audio subcarrier. Some modes may also support stereo audio in either the NICAM or A2/Zweikanalton format and these can be enabled if supported. Enabling stereo audio will increase CPU load.
Disable colour disables the colour subcarrier. This produces a high quality black and white image without dot crawl artefacts.
Invert video inverts the video polarity, so negatively modulated modes become positively modulated and vice versa.
Sample rate specifies the amount of samples in megahertz. It is best to leave this option as-is unless you have a specific need to change it. High sample rates increase CPU load but produce better image quality. If you experience choppy video (identified by a stream of the letter 'U' in the hacktv output), you may need to experiment with reducing the sample rate to a value that your PC can handle.
Setting the pixel rate will render the image in the specified rate and then resample it to the sample rate above. This is used to compensate for the bandwidth limitations of USB 2.0 SDR units such as the HackRF One. An example of where this would be used is with the VideoCrypt system, which works best with sample rates at a multiple of 14 MHz. A 14 MHz sample rate is too low for a good quality image on PAL-FM as is used on PAL satellite receivers. However a 28 MHz sample rate exceeds the bandwidth capabilities of USB 2.0. Therefore, setting the pixel rate to 28 MHz and the sample rate to 20.25 MHz gives good picture quality without exceeding the available bandwidth of USB 2.0.
FM deviation should be set to 10 MHz on HackRF devices when using PAL-FM on a standard IF. 16 MHz is the Astra standard but this exceeds the bandwidth capabilities of USB 2.0. The image will be darker than normal on 10 MHz so it is advised to use the brightness or contrast control on the receiver to mitigate this if supported. If using harmonics to pick up the signal via an LNB, each harmonic will increase the received deviation so this needs to be reduced to achieve the best result. Use 8 MHz for Ku band LNBs (second harmonic) or 4 MHz for Ka band LNBs (fourth harmonic). These will deliver a full 16 MHz deviation to the receiver at excellent quality.
VSB-AM filter attempts to filter the unwanted lower sideband in order to provide a cleaner signal. This can cause performance issues on some older systems.
When an FM mode is enabled, this option will display as FM video pre-emphasis filter and should be enabled if using an analogue satellite receiver. With this option enabled, the video is pre-emphasised using the CCIR-405 specification.
Widescreen signalling (WSS) on line 23
Adds data to line 23 of the VBI area which specifies the aspect ratio of the transmitted image. Most widescreen sets should set the aspect ratio to the specified value if supported.
Macrovision ACP
Enables Advanced Copy Protection (ACP) support. This inserts pulses into the VBI area which interfere with the gain control on most video recorders, preventing the video source from being reliably recorded.
VITS test signal
Adds a Vertical Interval Test Signal (VITS) to the VBI area. This is not visible on-screen.
VITC
Adds VITC timecode data to the VBI.
SECAM field ID
Adds "SECAM bottles" to the VBI for compatibility with older SECAM sets.
The options in this pane are only supported on D-MAC and D2-MAC modes.
Override channel ID
MAC modes 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. If not defined, this defaults to E8B5 (BSB's Movie Channel).
The other options allow you to reduce the quality of the audio stream to reduce CPU load. These options should be left at defaults unless you are experiencing dropouts or other performance issues because they will degrade audio quality.
hacktv supports the following output devices:
- HackRF One.
- Any SoapySDR-compatible device (not supported on Windows). Use the Antenna name option to specify an antenna name if required.
- Fresco Logic FL2000 (fl2k) VGA adapters via osmo-fl2k.
- File output. Use the File type option to specify the type of file.
The text field to the right of the Output device option is device specific. For HackRF and FL2000 devices, it allows you to address a specific device if more than one is attached. For SoapySDR, it allows you to specify any options that your device requires.
In the RF options frame, you can select the frequency or channel that you want to output on. Selecting either UHF or VHF will list the channels defined in the mode's band plan. Some modes support multiple band plans and it can be changed from the drop-down menu on the right hand side of the frame. Alternatively, you can also choose the Custom option and specify your own frequency in MHz. The HackRF One officially supports up to 6 GHz, but the absolute maximum is 7.25 GHz (7250 MHz). If you're using a satellite band plan, the frequency shown here is not the actual frequency that will be sent to hacktv. Rather, it's the frequency that corresponds with that shown in the tuning menu of a satellite receiver. See Satellite receiver settings for details.
The HackRF's output is quite noisy and will produce harmonics on each multiple of the base frequency. For example, transmitting on 200 MHz will generate harmonics of that signal on 400, 600, 800 MHz and so on. This can be exploited in FM transmissions to receive on frequencies higher than those officially supported by the device. Be aware that this can cause interference unless sufficient filtering is applied to the transmission chain.
The TX gain option allows you to specify the gain of the transmitter in decibels (dB). The higher the value, the stronger the signal. Valid values are between 0 and 47 dB. You may need higher gain at low VHF frequencies to counteract electro-magnetic interference (EMI).
The TX RF amplifier option enables the transmit amplifier in the HackRF One. This increases range further.
WARNING: Be extremely careful when enabling this option as it is very easy to permanently damage the amplifier. Do not enable this option if you're connecting a TV or receiver directly to the HackRF One. Additionally, make sure that the transmit aerial does not accidentally touch anything while the amplifier is active as this could cause a short or overload. If picture quality degrades when enabling this option, it's a sure sign that the amplifier has failed.
Gamma correction
Overrides the gamma of the output image. Lower values result in a darker image. Decimal values are supported.
Output level
Overrides the output level of the image. Lower values result in a darker image. Decimal values are supported.
Adjust volume
Does as it says, enter a decimal value here to increase or decrease the output volume.
Downmix 5.1 audio to 2.0
Downmixes 5.1 surround sound audio to two-channel stereo. This is recommended if using a 5.1 source and the audio output sounds incomplete.
Sound-In-Syncs
Adds Dual Channel SiS to the video signal. Requires a special decoder, supported on 625 line modes only.
See https://www.youtube.com/watch?v=K4su9kC0KIs for details.
Verbose output
Enable verbose output in the hacktv console.
Teletext is an information service that was used by many European broadcasters from the 1970s. It was discontinued in the United Kingdom following the end of analogue broadcasting in the early 2010s but is still used in some countries. BBC Ceefax is the most well-known service, but other notable services existed.
hacktv supports the insertion of teletext signals into the VBI data on 625-line transmissions using the standard TTI file format. If you have any TTI files on your computer, you can use the Browse button to select a single file, or a directory that contains multiple files. hacktv also supports teletext archive files with a .T42 extension.
If you don't have any teletext files, leave the field blank. In this case, hacktv-gui will feed a demo page to hacktv. Alternatively, you can use the Download button to download one of three online teletext services. This requires an active internet connection to download. The files are downloaded to your user Temp directory and will be deleted upon exit.
Teefax is an extensive hobby project developed by Peter Kwan. It was designed for use with the vbit2 software on a Raspberry Pi but works just fine with hacktv.
NMS Ceefax is a recreation of Ceefax by Nathan Media Services.
SPARK is operated by TVARK; a long running and well-known television presentation website.
One of the major uses of teletext was to provide subtitles. Enable the Subtitles (page 888) option to use this on a supported source. Like with the Subtitles option on the Source tab, this can be internal to the video or in a separate SRT file. If the video contains multiple subtitle streams, you can specify the index number of the stream you would like to use. The index numbers can be found in hacktv's output while it is running. Select page 888 to view the subtitles.
hacktv supports the following video scrambling systems. When you select a system from the drop-down menu, you can then select an access mode from the drop-down menu beside it.
-
VideoCrypt
A line cut-and-rotate system used most notably by Sky Television in the United Kingdom from February 1990 until September 2001. It was also used by Sky New Zealand for terrestrial transmission. VideoCrypt is almost fully supported and is compatible with real hardware and viewing cards. A never-used facility to use dumb memory cards in pay-per-view mode is also supported. Telecom Éireann (Eircom) CallCards are known to work in this mode and are readily available, but require some data to be dumped from the card.
All Sky (UK) viewing cards should be supported if they are still active. The issue number is stamped on the bottom right corner of the card on some 07 cards and all later issues. Earlier cards have the issue number as the first two digits of the card number. Sky Digital cards are not supported as these use a completely different system.
VideoCrypt-II is supported in free access mode (no card required). Both VideoCrypt-I and II can be used simultaneously in free access mode. Captain Jack's fork also supports conditional access mode with viewing cards supplied by Multichoice Europe. This can be used alongside VideoCrypt-I, for example VideoCrypt-I with a Sky P11 viewing card and VideoCrypt-II with a Multichoice card. -
Nagravision Syster
A line-shuffle system used by various broadcasters in Western Europe - e.g. Premiere Germany, Canal+ in France (and others) and various Spanish broadcasters. Audio inversion is also supported and can be enabled by selecting the Scramble audio option. Some decoders support a cut-and-rotate variant of Syster and this is also supported. -
VideoCrypt-S
A line-shuffle variant of VideoCrypt, used by the BBC in the United Kingdom for their overnight BBC Select service. While VideoCrypt-S does support audio inversion, hacktv does not yet support it. Compatible with a real BBC Selector box... if you can find one! -
Discret 11
An early scrambling system used in Europe - e.g. Canal+ in France until 1995, and part-time by RAI in Italy on their satellite transmissions. Audio inversion is also supported and can be enabled by selecting the Scramble audio option. This is supported in the same access modes as Syster. -
D-MAC/D2-MAC
Like DVB, MAC defines a common scrambling algorithm, supported in both single and double line cut-and-rotate modes. hacktv supports this in free mode with no conditional access. At least two CA systems were in use.
EuroCrypt is fully supported. This was a scrambling system used mainly in Scandinavia on D2-MAC systems. Two variants, EuroCrypt M and EuroCrypt S, were in common use and both are supported with real hardware.
A large number of cards are supported from a number of Scandinavian broadcasters such as TV1000, FilmNet and NRK.
Audio scrambling is also supported and can be enabled by selecting the Scramble audio option.
EuroCypher was used by British Satellite Broadcasting (BSB) on the UK DBS service from April 1990 until December 1992. This is not supported but BSB receivers should be able to descramble in free mode.
The GUI settings tab contains settings which are specific to the GUI. These settings are saved to the Java preferences store and retained on exit.
Path to hacktv is where you specify the location of the hacktv application. This will default to /usr/local/bin/hacktv on Unix-based systems, and to the application directory on Windows. The Download button (Windows only) will allow you to download a pre-compiled Windows binary of hacktv which is ready for use. These builds are maintained by me. You'll be prompted to download either the fsphil or Captain Jack build, see below for details.
Detected build will show fsphil or Captain Jack depending on the selected file. Captain Jack's fork supports more features but can be slower to receive updates, whereas the original fsphil build is generally more reliable.
Generate syntax only
Displays the hacktv command line syntax in the status bar without running hacktv. This can be copied and pasted into a command prompt or terminal if desired.
Always use local copy of modes files (do not download)
The modes files (fsphil.ini or captainjack.ini, as well as bandplans.ini) are data files that contain the supported video modes, scrambling systems, band plans and some other options. By default, the latest copy is downloaded from the internet when hacktv-gui is started. This ensures that new options are available to you without the need to download a new version of the application. However, if you would prefer to use the internal copies (or a custom-built copy), you can enable this option. This will also suppress the prompt you will receive if such a file is detected in the application directory.
Do not check for updates on startup
Disables the automatic checking for updates when the application starts up. You can still check for updates manually via the Help menu.
Ceefax (NMS) region
Specifies the region to use when downloading Ceefax pages. This affects page 100, as well as local news and TV listings. The default setting is Worldwide, which contains no region-specific data.
This option was disabled in the 2024-10-30 release. The data required to make use of it is currently unavailable. It may return in future.
Theme
Changes the appearance (look and feel) of the application. The themes in this list are those that are supported by your Java runtime environment. In addition, if FlatLaf is available, you can choose it here.
Reset all settings
Removes all settings from the Java preferences store and exits the application. This can be used for troubleshooting purposes or as an uninstaller.
This dialogue allows you to configure settings related to satellite receivers.
LNB local oscillator (GHz)
Although you might see a high frequency (10 GHz or more) in the tuning menu on a satellite receiver, this isn't what the receiver is actually getting. Feeding such a high frequency signal directly from a satellite dish is impractical, so the LNB on the satellite dish uses a local oscillator to downconvert the signal to a more usable frequency, usually in the range of 950 to 2150 MHz, which is much more practical. This is known as an intermediate frequency (IF).
Enter the local oscillator frequency that is set up on your satellite receiver. This will be used to calculate the correct IF to send to the satellite receiver. The default is 9.75 GHz, which should work with most Astra receivers manufactured from 1994 onwards. If your receiver is advertised as "Astra 1D compatible", it is most likely set up for 9.75 GHz. Older receivers used a 10 GHz local oscillator. If this setting is incorrect, you may find that the frequency displayed in hacktv-gui does not match that on your receiver's tuning menu.
Apply these settings to custom frequencies
By default, custom frequencies will be interpreted as they were entered. This may cause an issue if you manually enter a Ku-band frequency, as the HackRF can only transmit up to 7.25 GHz. Enabling this option will apply the local oscillator setting to custom frequencies too, but only on modes with a satellite band plan specified in the modes file.
Reception device
This combobox has four options:
- Direct (IF): This calculates the IF directly from the base frequency without any additional trickery. Use this if you're connected directly from the SDR to a satellite receiver.
- Ku band LNB: This divides the Ku band frequency by the harmonic specified below, allowing the signal to be picked up on a standard Ku band LNB.
- Ku LNB with BSB box: This performs some trickery with the base frequency to allow a BSB D-MAC satellite receiver to work with a standard Ku band LNB.
- Saorsat Ka LNB: This is a setting that I'm sure that 99.9999% of you out there will never use! But I do, so it's there. Like the above option, it performs some trickery with the base frequency to allow a satellite receiver to work with a Saorsat Ka band LNB. This only supports the fourth harmonic.
Harmonic settings
Do not use these settings unless you know what you're doing! And definitely don't use this outdoors! So why is this here?
The Astra PAL-FM transmission spec called for a 16 MHz deviation. However, due to the limitations of the HackRF, it's only possible to get up to about 10 or 11 MHz, which results in a dull picture. We can get around this by exploiting the leaky nature of a HackRF to pick up a signal on a second, or subsequent, harmonic. The hacktv team discovered that transmitting a signal at half the Ku band frequency (e.g. 5.659 GHz) with 8 MHz deviation, will produce a harmonic at the intended frequency (e.g. 11.318 GHz) at full 16 MHz deviation. I took this one step further, and discovered that it is possible to pick up a signal on the fourth harmonic using a Ka band LNB. In this case, transmitting at 4 MHz deviation produces an equivalent of 16 MHz on the fourth harmonic.
Select the harmonic that you plan to use, and the output frequency will be altered accordingly.
Displays the output from hacktv while it is running. This will show information from ffmpeg about the file or stream currently being played, and may also show other messages related to video scrambling systems or status messages. If you notice a stream of the letter 'U' in the hacktv output, and you're experiencing choppy video, this is a sign that your PC is having difficulty with the current settings.
The File menu allows you to manage HTV configuration files. These files contain the application's settings at the time the file was created. This allows you to quickly recall your settings from a previous session.
New
Closes the currently open file (if any), clears all settings and starts again fresh.
Open
Opens a file browser box to select a previously saved HTV file.
Save and Save as
Saves the current settings to a HTV file. If a file is currently open, Save will silently update the file, while Save as will allow you to save a new file with a different name. If no file is currently open, both options work the same way.
The MRU (Most Recently Used) list displays the last four HTV files that were opened. This list can be cleared on the GUI settings tab by pressing the Clear MRU list button.
Exit
Exits the application. If hacktv is running, it too will be closed.
The Templates menu contains two pre-defined templates to help with setting up an analogue satellite receiver. The output frequency will vary, depending on the configuration specified under Satellite receiver settings. The deviation will also be set according to the harmonic selected.
Astra analogue STB (9.75 GHz)
Loads recommended settings for a PAL-FM satellite receiver. The tuning frequency will be set to TCC (10.994 GHz).
BSB D-MAC STB
Loads recommended settings for a British Satellite Broadcasting (BSB) receiver. The tuning frequency will be set to the Galaxy channel.
The Help menu contains links to this Github page and the ability to manually check for updates.
Wiki page
Links to this wiki.
Github repository
Links to https://github.com/steeviebops/hacktv-gui/
Check for updates
Manually checks for updates to the application. This works by downloading https://api.github.com/repos/steeviebops/hacktv-gui/releases/latest and comparing the version number to the current version. No other information is transmitted.
About
Displays copyright information and also shows the currently active Modes.ini file source and version.