Hydrus Companion

Browser extension for Hydrus

Main features

• Highly configurable
• Displays page status on toolbar icon (see below for more info)
• Context menus for sending current page/link/image to Hydrus, optionally with tags (predefined or user input) and to specific target page
• Looking up images on IQDB and/or SauceNao and automatically sending results to Hydrus
• Sending current tab, all tabs, tabs to the left/right, tabs matching URL/title filter to Hydrus
• Send links to Hydrus by hovering + pressing shortcut
• Send all links from selection to Hydrus
• 100% user-defined, highly customizable menu and shortcut system
• Highlight links/images already in Hydrus
• Look up images on various reverse image search sites
• Supports using multiple Hydrus clients and switching between them

Installation on Chrome and derivatives (tested on Chrome, Chromium, Vivaldi and Brave)

1. Clone or download this repo
2. Open the Extensions page in your browser, enable developer mode
3. Click on the button for loading unpacked extensions (top left), select the hydrus-companion directory to install it
4. Do the basic setup procedure to connect the extension to Hydrus (see below)
5. (Optional) If you get annoying messages about using unpacked/dev mode extension, see the end of this document for a potential fix.

To update, just do git pull (or redownload the repo), then go to your browser's Extensions page and reload the extension. You will need to reload any tabs opened before the update to get the extension working correctly on those pages.

If you use Chrome, it will probably nag you about using an unpacked extension not from the Chrome Store. The extension is not on the store because the only way to get on the store involves having a Google account and sharing your personal data (payment details) with Google, which I refuse to do. I recommend that you use Brave, ungoogled-chromium or another Chrome-based browser which is less of a locked down spyware than Chrome itself.

Installation on Firefox (making an xpi from git source)

⚠️ Firefox version of extension is not officially supported or tested! And can break after any update to the repo! ⚠️

❗ Currently downloading cookies doesn't work, but sending cookies via API to Hydrus or Hydownloader works.

For this method to work, you will need a Firefox version 131+ that support use of unsigned extensions:

• Firefox Developer Edition here
• Firefox Nightly here

After getting an appropriate version, follow the next steps:

1. Clone this repo
2. Delete manifest.json (it's for Chrome), then rename firefox-manifest.json to manifest.json
3. Zip the contents of the hydrus-companion directory (but not the directory itself!) excluding hidden .git folder and change the extension of the zip file to xpi
4. Open about:config in Firefox and set xpinstall.signatures.required to false
5. Go to the extensions page and use the 'load extension from file' option to load the xpi
6. Do the basic setup procedure to connect the extension to Hydrus (see below)

Basic setup - connecting the extension to Hydrus

1. Enable the client API in Hydrus under services > manage services > client api: the 'run the client api?' needs to be ticked
2. Navigate to your client API under services > review services
3. Click add > manually on the client API
4. Tick all the boxes (or at least the 'add urls for processing' permission for basic functionality)
5. Copy the API access key into Hydrus Companion's options page and save it

Note on menu configuration

The default menu configuration mainly serves as an example. It is not intended to be used as is. You should review and customize it as you see fit. See the documentation included with the extension for details.

Shortcuts

Shortcuts are not configured in Hydrus Companion's options page, but in the browser-wide extension shortcut page. On Chrome based browsers, open the Extensions page and use the top left menu button (next to the "Extensions" text) to switch to the shortcuts page. On Firefox, use the gear menu on the Extensions page and select the 'Manage Extension Shortcuts' item.

Page status info

Various status messages may appear on the toolbar icon:

• No status text: no connection to Hydrus or the current tab has invalid URL
• ???: Hydrus does not recognize this URL
• Post: Hydrus recognizes this URL as a post page
• File: Hydrus recognizes this URL as a file URL
• Gall: Hydrus recognizes this URL as a gallery page
• Watch: Hydrus recognizes this URL as a watcher page
• Checkmark with green background: there are one or more files in your Hydrus with this URL ("you already have this")
• X with red background: there are one or more deleted files in your Hydrus with this URL ("you deleted this")
• Checkmark and X with yellow background: there are both deleted and non-deleted files with this URL in your Hydrus (can happen with e.g. pixiv posts with multiple images, where you keep some but also delete some images from the same post)

License

GPLv3+.

Potential fix for Chrome and Chrome-based browsers bitching about running the extension in unpacked/developer mode

The following instructions to get rid of the annoying message about developer mode were contributed by a user on Discord (thanks):

chrome for windows:
1. add the extension to chrome (with developer mode on)
2. copy the extension id. write this down
3. close chrome
4. open regedit (run: regedit)
    navigate to: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\ExtensionInstallWhitelist
        if any parts of this paths dont exist, create them:
        right-click -> new -> key (be aware the key names are case sensitive)
    once in the ExtensionInstallWhitelist directory (key) right click and add -> new -> string value
    give it the name 1 (one)
    give it the value <your extension id from step 2. above>
5. start chrome. you may have to tinker with enabling the extension from chrome://extensions as it may be forcefully disabled from before the regedit fix.
   just enable it, then disable developer mode. restart chrome again.
   you may see a developer-warning only once and never again. this one warning is likely a chromium bug.

brave for windows:
1. add the extension to brave (with developer mode on)
2. copy the extension id. write this down
3. close brave
4. open regedit (run: regedit)
    navigate to: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Policies\BraveSoftware\Brave\ExtensionInstallWhitelist
        if any parts of this paths dont exist, create them:
        right-click -> new -> key (be aware the key names are case sensitive)
    once in the ExtensionInstallWhitelist directory (key) right click and add -> new -> string value
    give the string the name "1" (one, as in the number)
    give the string the value <your extension id from step 2 above>
5. start brave. you may have to tinker with enabling the extension from chrome://extensions as it may be forcefully disabled from before the regedit fix.
   just enable it again, then disable developer mode. restart brave again.
   you may see a developer-warning only once and never again. this one warning is likely a chromium bug.

Please let me know whether these instructions help solve the issue or not.