Hush Help

Introduction

Welcome to the Hush help file. Please note if viewing in the KVIrc Help Browser you may need to opposite click and select "Reload" to see updated help files after upgrading version.

This help file was updated for v0.3.1 release. The content may be behind if the Hush version is greater than the one written here.

Installing

Important Message for Users Upgrading below v0.2.7

If upgrading from a version that is lower than v0.2.7 make sure you export your hush settings prior to installing the new version! The upgrade routine will remove your settings file and you will have to enter all your settings again. To export your settings go to Hush -> Options -> Export Settings and save to a file. Import from this file after upgrading.

To install Hush:

  1. Download Hush and extract the .tar file (use 7zip on Windows to extract tar file)
  2. In KVIrc, go to menu: Scripting -> Execute Script (or press Ctrl+Shift+X)
  3. Browse to and select the install.kvs file in the extracted files
You should see some messages echoed in one of the IRC windows:

Attempting to register addon "Hush" with version *.*.*
Addon successfully registered
Hush installed. Click Hush button on toolbar or press Ctrl+Alt+H to open Hush.

Hush is now installed and you should see a new button Hush toolbar icon on KVIrc's toolbar area. Clicking that button will open the main Hush window. You can also press Ctrl+Alt+H to open the main Hush window while in KVIrc.

When I open [one of] the Hush window, it doesn't look like the screenshots? Resize the window. Hush works on different operating systems and screen configurations. Resize the windows so they look good to you.

Hush Main Window

Clicking the Hush button on the top toolbar in KVIrc will open the Hush main window.

The main window offers access to all of the settings in the script. Hush needs at least 1 watched channel and 1 search value for passive searching to begin operating, or needs 1 watched channel and for Instant Searching to be enabled for instant search to begin operating. Instant Search is enabled by default.

Configuring

Setting Channels

To modify your watched channels:

  1. Open the main Hush window by clicking the Hush button on the toolbar in KVIrc (or press Ctrl+Alt+H)
  2. Click the Channels button
      3. To add a channel:
    1. Click inside the text input box and type in the channel name to watch
    2. Click the Add button or press Enter to save the channel to the watched list
      To remove a channel:
    1. Click to highlight channel names to be removed in the watched list (you can highlight multiple items at the same time)
    2. Click the Remove button or press the Delete key or press the Backspace key
  3. Close the Channels window

Setting Passive Searches

To modify your passive search queries:

  1. Open the main Hush window by clicking the Hush button on the toolbar in KVIrc (or press Ctrl+Alt+H)
  2. Click the Searches button
      3. To add a search:
    1. Click inside the text input box and type in something to look for. This can include wildcard characters * and ? but is not a regular expression.
    2. Click the Add button or press Enter to save the search to the searches list
      To remove a search:
    1. Click to highlight searches to be removed in the search list (you can highlight multiple items at the same time)
    2. Click the Remove button or press Delete or press Backspace to remove the search from the searches list
  3. Close the Searches window

Altering Searches

To adjust the season or episode values of your existing searches:

  1. Open the main Hush window by clicking the Hush button on the toolbar in KVIrc (or press Ctrl+Alt+H)
  2. Click the Searches button
  3. Click to highlight searches to be altered in the search list (you can highlight multiple items at the same time)
  4. Click any of the Season or Episode "Up" and "Down" or Episode "Reset" buttons to increase or decrease either the season or episode value or to set the episode value back to 01 in the highlighted search items. If a search item does not contain the sXXeXX format, it will not be altered.
  5. Close the Searches window

Setting Search Exceptions

Search exceptions allow you to ignore lines that match a search condition, but also contain something else. You can, for example, search for 1080 quality item but create a search exception for CAM which will make it ignore any CAM items. Be aware that excepting "CAM" will ignore anything that contains CAM also. You may need to do things like excepting ".CAM" or ".CAM." for example to get the results you want.

Exceptions can also be used to ignore false positive search matches. Some XDCC announce channels may have lines that announce when a new item has become available. This is usually because they contain the filename that matches a search you are looking for. If lines like this appear in the Found Content Window, you can inspect the offending line and add something from it as a search exception.

To modify your search exceptions:

  1. Open the main Hush window by clicking the Hush button on the toolbar in KVIrc (or press Ctrl+Alt+H)
  2. Click the Searches button
      3. To add a search exception:
    1. Click inside the search exception text input box and type in an exception value. This can include wildcard characters * and ? but is not a regular expression.
    2. Click the Add button or press Enter to save the exception to the exceptions list
      To remove a search exception:
    1. Click to highlight search exception to be removed in the search exceptions list (you can highlight multiple items at the same time)
    2. Click the Remove button or press Delete or press Backspace to remove the search exception from the search exceptions list
  3. Close the Searches window

Additional Options

To set more options:

  1. Open the main Hush window by clicking the Hush button on the toolbar in KVIrc (or press Ctrl+Alt+H)
  2. Click the Options button
  3. Select the Basic tab
  4. Change the Found Content window name by editing the name in the text input box.
  5. Toggle Silence Watched Channels by tick/unticking the checkbox.
  6. Toggle Smart Mode by tick/unticking the checkbox.
  7. Toggle displaying SSL DCC sending options by tick/unticking the checkbox.
  8. Export Hush settings to a file on disk by clicking the Export Settings button, selecting where to save and clicking Save button.
  9. Import Hush settings from a file on disk by clicking the Import Settings button, selecting which file to load from disk and clicking Open button..
  10. Clear the smart mode Haystack by clicking the Clear Haystack button.

The Found Content Window

The Found Content Window is where Hush will display any passive searches it finds, any pack requests made from instant search and any DCC messages it is monitoring. It will automatically appear in the channel list when it finds a match to any of your searches. The Found Content window will show packs from multiple networks/channels that you are connected to. Hush knows which channel and network the pack is from and will send the request to the correct place if you click to fetch a pack.

Silence Watched Channels

Many users prefer to silence the channels that show the xdcc announcements of packs from bots (there are thousands of them!). Hush will stop all channel messages in your watched channels if you tick this option.

Smart Mode

Smart Mode makes Hush track which bot is offering a pack that matches one of your searches. Smart Mode will detect if a bot reannounces a pack Hush has seen before and will prevent it being shown in the Found Content window again. A pack is deemed different if:

  1. The bot name changes
  2. The pack name changes
  3. The pack file size changes
If Smart Mode is working, your Found Content window should eventually stop getting new packs displayed in it - as long as you don't change your searches. If Smart Mode is off, you will forever see "new" matches in the Found Content window (hint: they aren't new, they're repeats!)

SSL Send Option

SSL DCC sending option will display single-click links for sending via SSL DCC in your search matches.

ZNC Push Notifications

ZNC Push Notifications option will forward any searches Hush matches through your ZNC server using the ZNC Push module. For this option to work you must have:

  1. a ZNC server that you are accessing IRC through (ZNC Website)
  2. the ZNC Push module installed on the ZNC server (ZNC Push Module)
  3. the ZNC Push module configured (use any service you like, it doesn't matter - as long as it's configured and working. I found Telegram pretty easy to set up)

Prevent ZNC *push query window appearing

Prevent ZNC *push query window appearing option will stop the *push query window appearing in the channel tree list. Note: this will stop the *push query window from appearing all the time. If you need to use the *push query, you will need to untick this option in Hush Options.

Import/Export Settings

Export Settings will let you save all your Hush settings to a file on disk. All settings are saved: channels, searches and option values.

Import Settings will let you load Hush settings from a file on disk. If the file loaded is not a valid KVC (KVIrc Config) formatted file then no settings will change in Hush but no warning will be given. Any existing settings will be overwritten. Use carefully.

Clear Haystack

Clearing the Haystack will reset the tracking that Smart Mode has done since KVIrc started. If you are trying to find something that perhaps you have found before and it wont appear in the Found Content window, you should try clearing the Haystack. Please note that closing the Found Content window does not clear the Haystack! Restarting KVIrc will clear the Haystack.

After Configuration

What to do now? Wait. Hush is a passive search. This means that it is watching the channels that announce packs. When something in those channels matches something you are searching for, Hush will log it in the found content window for you. The found content window is named "Hush" by default (you can change this also) and will appear in your channel list area automatically as soon as something is found.

Suggestion: To get started and see how it passive searching works, search for something that will appear straight away such as "mkv".

Instant Search

From v0.3.1 onward Hush has an Instant Search system. You can bring up the Instant Search window by pressing Ctrl+Alt+I.

The Instant Search window will display how many pack announcements are currently searchable in the lower left corner of the window. Enter a search string in the input box and press Enter key or click the LAUNCH button to run the search. Depending on the number of results a search can take a few seconds. When the search is done all the matching results will be shown in the results list and the total number of matches found will be shown in the lower right corner of the window.

To search for content:

  1. Enter what to search for. Wildcard characters * and ? are accepted.
  2. Click the LAUNCH button. Alternatively just press enter.
  3. Select a pack by clicking on it in the result list.
  4. Optionally choose whether to request via SSLDCC. The bot and your IRC client must support SSLDCC for the send to work.
  5. Click the Request Pack button.
The Found Content Window will be display a notice about the requested pack. You can track the transfers activity in the FCW or KVIrc's File Transfers window.

The result list shows information about each pack that your search matched. The list is sorted by Pack Name then Age by default. You can change the sort order by clicking the column titles.

To set Instant Search Options:
  1. Click the Instant Search tab
  2. Toggle the Instant Search system by tick/unticking the checkbox.
  3. Change the database buffer setting by editing the spinbox. Type a value or use the arrow buttons.
  4. Change the write buffer setting by editing the spinbox. Type a value or use the arrow buttons.
  5. Reset the instant search database by clicking the Reset Database button. This will remove the database file and start with a new empty database.
A little more about the instant search system and its settings:

Instant search works by logging the messages from your watched channels. It stores the announce data locally on your computer so you can search privately.

The database buffer setting defines how often announce data will be discarded from the database. The value of this buffer is in minutes, because as pack announce data gets older, it becomes redundant and/or unreliable, so it is more economical to delete it once it reaches a certain age. If you set this to 60 minutes, when you use instant search all the results will be no older than 60 minutes. The higher you set this value, the more disk space the database file will consume, but you have access to older data.

The write buffer setting defines how often announce data will be written to the database. The value of this buffer is in entries. An entry is equal to one pack announcement message. When a message occurs in one of your watched channels, the message is analyzed and if it is deemed to be a pack announce it is added to a temporary storage array in memory. When we have enough entries in that array, the entire contents of the array is saved to the database. The time it takes for this to happen will vary depending on how many channels are being watched, how many bots there are in each channel, how often the bots announce packs on offer, lag and so on. The higher you set this value, the less frequent the database will be written to and the longer it takes for new announce data to become available for searching. The average time with the default settings, watching 5 major channels roughly equals a database write and new searchable data every 40 seconds.

If you experience program lag with KVIrc you might want to disable the instant search to see if it is contributing to any problems. The toggle to enable or disable instant search completely disables all the code involved with the system. To entirely disable it, you can disable the onChannelMessage::hushInstantSearch Event Handler in KVIrc, which will prevent the single line of code that will run (it checks if the enable toggle is set and halts if it isn't) if instant search is disabled via the Hush settings.

Debug Mode

Most users are probably not interested in this, but if you have trouble with something you can turn on Hush's own debug mode by opening the Options window and pressing 4444 while the Options window is up. A Debug Messages window will appear in the channel window list where all debug messages will be sent.

Debug mode is useful if you can't find things like where your config files are, most of that info can be found in debug mode messages.

Troubleshooting

When I install Hush there is no indication it is installed? - The addon manager will display some feedback when it registers an addon and there should be a message saying Hush is installed. You might need to check your channel windows and if you use split window setup the addon feedback will be in the top split window. You should also see a new toolbar button somewhere, it has spiral on it.

When I press the Hush toolbar button, or press Ctrl+Alt+H in KVIrc I get the following error in a status window: "[KVS] Runtime error: Class 'hush::main' is not defined [KVS] In script context "kvirc::corecall(run)", line 6, near character 12" - Most likely the hush class has not been built, maybe someone has altered something in the class (maybe you?) and it needs rebuilding. You can check this by going to menu: Scripting -> Edit Classes and in the class editor's tree on the left side expand the hush namespace. The icons for the all the classes should be coloured red/green/blue and not be grey. If any of them are grey, click the Build button in the bottom right corner and try opening Hush again. If the class won't build (icons stay grey, usually a dialog appears saying it can't build) either the class code has been altered or maybe the release of the script is bad. Uninstall and try redownloading and reinstalling the Hush script.

I lost the Hush toolbar button somehow? Opposite click anywhere on the toolbar area, go to Toolbars, Customize... click the Generic tab, find Hush action in the list, click and drag it back to the toolbar area wherever you like. Click Close on the Customize Toolbars window.

Something is not working, is there a debug mode? (Or you are a coder and you want to see what's going on) From v0.2.4 onwards Hush has a debug system being written into it. To turn it on/off go to KVIrc's Class Editor (Ctrl+Shift+D) and in the class tree go to: hush -> main -> constructor, at the top of the constructor code somewhere is a variable called @%debug. For debug mode, set it to $true. For no debug mode, set it to $false.
From v0.2.9 onwards you can open the Options window and press 4444 to toggle debug mode on and off. If you restart KVIrc you will need to turn debug mode back on again using this method.

I don't want to see pr0n in my search results? Use search exceptions in Hush > Searches. Add an exception for "xxx" and it will hide anything matching that, which is 99.9% of all pr0n on offer.

I have installed and configured Hush. The Found Content Window has appeared in the KVIrc channel tree list, but I can't click to show the window? - The Found Content Window is "undocked" from the KVIrc main window. You may accidentally do this at some stage and not realize. To fix, opposite-click the Found Content Window name in the channels tree list and then click Dock.

I am not getting push notifications from Hush? From v0.3.0 onwards Hush has push notification support only if you use a ZNC server to connect to IRC and you have the ZNC Push module installed on the server and it is configured and working. See ZNC website to get started.

When I click on Channels/Searches/Options button, nothing happens? For some reason, if you alter the channels, searches, options class code in Class Editor, then rebuild the class this happens. You need to also alter (just add a new line somehwere) the main class and rebuild that too. That should fix this problem if you alter the class code for some reason.

When I request a pack, the bot sends a different file to what I want? This happens because time has passed between when Hush found the pack and when you have requested it. Bots change the pack number used to request a pack as time goes on. Usually Hush will find the new pack number when the bot announces the pack again. You should always try to request from the most recent announcement of a pack as this lowers the chance of this happening.

When I use Instant Search, I get no results? Either there is no data in the database or your search doesn't match anything in the database. Check if: 1. Instant Seach is enabled in Options > Instant Search 2. the write buffer is not set too high (try lowering this value if you are only on 1 or 2 channels) 3. the database buffer is not set too low (try increasing this value if it is really small. 60 minutes is the recommended setting) 4. your search has no matches. Try searching for something broader, like "mkv" and it should show you results.
There is also the possibility that the instant search database file can't be created. Turn on debug mode and press the Reset Database button in Options > Instant Search. It should tell you if there is a problem making the database. 99% of the time under UNIX environment directory permissions cause issues like this.

When I sort the instant search results by pack number or grabs it doesn't sort the numbers correctly? This is because the listview widget is treating the values in that column as strings instead of numbers. If you used Windows deacades ago you will remember it sorted numbers like this too. I don't really have any control over this mechanism in the software except to zerofill the numbers so they sort correctly and I decided against that for aesthetic reasons. We will just have to suffer in our jocks.

Uninstalling

To uninstall Hush:

  1. In KVIrc, go to: Settings -> Manage Addons
  2. Highlight Hush in the installed addons list
  3. Click the trash can button (Delete selected addon)
  4. Confirm uninstall by clicking Yes button

See Also

  1. Change Log