Extensions

Extensions are gPodder’s mechanism for adding optional features and allowing easy customizability. Some extensions are already activated by default if you are running a specific environment (e.g. Ubuntu Unity support in gPodder 3 is implemented as an extension).

Sometimes the ordering of extensions is important. gPodder parses the filenames of extensions for a prefix, like “50_”. When it finds a prefix like this, it sorts according to said prefix, with lower numbers being run earlier. If two extensions have the same priority, they will be sorted in alphabetical order according to their base name. If multiple instances of an extension are desired, the base name must be different, not just the prefix.

Extensions found within the user extension directory with the same base name (regardless of whether the prefix matches, or is present at all) override extensions provided with gPodder in the system directory.

Note that this allows for easy changing of extension priorities. Simply create a symbolic link in the user extension directory which points to the existing extension in the gPodder system directory and name it the same except with a different numerical prefix. This works even if the extension in the system directory does not have a prefix at all!

As an example, if you wished to change “20_audio_converter.py” to “50_audio_converter.py”, all you would need to do is, in the user extension directory, make a symbolic link called “50_audio_converter.py” which points to the original extension in the system directory.

This would also work if you wished to create multiple instances of the same extension. For example, if you wished to have a “command_on_download.py” which runs early and one which runs late, you could create two symlinks in the user extension directory, “10_command_on_download.py” and “80_command_on_download_late.py”.

Extensions with no priority prefix automatically get priority 99. Therefore if an extension needs to run later than everything, use a value of 100 or greater.

Default Extensions Included With gPodder

The following extensions are included with gPodder 3:

Audio Converter - Transcode audio files to mp3/ogg
Convert video files to MP4 for Rockbox - Converts all videos to a Rockbox-compatible format
Enqueue in media players - Add a context menu item for enqueueing episodes in installed media players
Filter episodes - to prevent automatic download of episodes matching a pattern, useful for mixed feeds
Gtk Status Icon - Show a status icon for Gtk-based Desktops
Gtk+ Desktop Notifications - Display notification bubbles for different events.
Minimize on start - Minimizes the gPodder window on startup.
MPRIS Listener - listen to notifications from MPRIS-capable players and translate them to gPodder’s Media Player D-Bus API
Normalize audio with re-encoding - Normalize the volume of audio files with normalize-audio
Notification Bubbles for Windows - ‘Display notification bubbles for different events.
Remove cover art from OGG files - removes coverart from all downloaded ogg files
Rename episodes after download - Rename episodes to “.” on download
Rockbox Cover Art Sync - Normalize and sync channel coverart to Rockbox or other portable media players
Search for new episodes on startup - Starts the search for new episodes on startup
Sonos - Stream podcasts to Sonos speakers
Subtitle Downloader for TED Talks - Downloads .srt subtitles for TED Talks Videos
Tag downloaded files using Mutagen - Add episode and podcast titles to MP3/OGG tags
Taskbar Progress - Displays the progress on the Windows taskbar
Ubuntu App Indicator - Show a status indicator in the top bar.
Ubuntu Unity Integration - Show download progress in the Unity Launcher icon.
Video Converter - Transcode video files to avi/mp4/m4v
Youtube_dl - enhanced youtube subscriptions and downloads using youtube-dl

How To Write Your Own Extension

Extensions are a great way to customize your gPodder workflow: you’ll be able to customize the UI, rename, modify or trigger external programs when episodes are downloaded, etc..

Getting started

Extensions are loaded from the Extensions folder in the gPodder Home Folder. The folder doesn’t exist by default, so create it.
An example extension is available here. Copy it to GPODDER_HOME/Extensions and restart gPodder.
Extensions are activated from the Extensions pane of the Preferences dialog. Activate the Hello World Extension to get a item in the Extras menu called Say Hello.
Modify the Message, restart gPodder and see the updated notification when you click Say Hello.

Doing something useful

Maybe an existing extension does something similar to what you want (rename after download, tagging, run a command after download, …). Find inspiration in its source code.

To see how an extension is loaded and every available callback, take a look at extensions.py; every method annotated with @call_extensions can be overriden in your extension. Check its parameters and return type.

gPodder’s model is quite straightforward. Given an episode e:

get its title via e.title, its url via e.url
get the channel’s subscription url via e.channel.url.

Debugging your extension

If your extension doesn’t appear in the list, be sure:

that its __only_for__ or __disable_in__ instructions (if any) apply to your system.
to run gpodder in debug mode (gpodder -v, Windows) and check that it’s found and there isn’t any error message: ``` [gpodder.extensions] DEBUG: Found extension “hello_world” in …/Extensions/hello_world.py [gpodder.extensions] INFO: Module loaded: …/Extensions/hello_world.py

```

You should run gpodder -v anyway, because any log with lower priority than logger.warn is suppressed by default.

Feel free to ask for advice in the mailing list or as github issues: we are always pleased to see you customize gPodder to your own needs.

Also, you may have to modify code in gPodder itself to achieve a particular goal. This is OK: no need to recompile anything: just edit the .py and restart…