User Manual

From gPodderWiki

The gPodder User Manual

This is a Wiki page. Feel free to contribute and make it even better :)
Use Ctrl+F (Mac OS: Option+F) to search on this page in your browser.

gPodder is a podcatcher. I.e. it allows podcast (RSS) feeds to be subscribed to, checking for new episodes and allowing the podcast to be saved locally for later listening. This user manual covers installation, configuration and normal and advanced usage. If you feel that something is missing, feel free to contribute. Some information is outdated or only relevant for specific variants (e.g. the Maemo port). Please fix any obvious mistakes you find.

[edit] Installation

On Linux and Unix-like systems you might have to be root (or use sudo) to install packages onto your system.

Under major RPM-based Linux distributions, gpodder is easily installed using yum:
```
yum install gpodder
```
On Debian-based Linux distributions (Ubuntu, Debian, etc..) you can use the following command:
```
aptitude install gpodder
```
On Windows, you simply unpack the .zip file and start gPodder from the extracted folder (no installation necessary)
- If the installation is an upgrade, you could copy the old folders config and downloads to the new gpodder folder, and your old podcast files will be included in the upgraded version of gpodder. As long as you use the same disk, the copy operation is fast. No real data transfer.
On Mac OS X, please follow the Mac OS X installation instructions using MacPorts

The configuration files and database will be stored in .config/gpodder/ in your user's home folder (i.e. /home/username/.config/gpodder/).

[edit] Configuration

gPodder has numerous configuration options to set its behaviour: how it plays podcasts, handles downloads, synchronizes with mobile devices, and many others.

To change gPodder's configuration, open the Preferences dialog box by choosing Podcasts > Preferences from the menu bar, clicking the Preferences button on the toolbar, or typing Ctrl-P. Then click the tab containing the options you want to change..

[edit] General Preferences

Click the General tab to see gPodder's general configuration options.

Audio player: Use this drop-down list of compatible audio players installed on your system to choose the one gPodder uses to play audio podcasts.

You can also click the Edit button next to the list to enter a custom audio player command. For example, you might want to run the player with some additional options, or choose a different player that does not appear on the list.

Video player: Use this drop-down list to choose the video player gPodder uses to play video podcasts. This option works the same as the Audio player option, except that it shows media players capable of playing video files.

Enable notification bubbles: Check this box if you want gPodder to display a bubble on your desktop when it finishes a task, such as completing a download or syncing your MP3 player.

Show icon in system tray: Check this box if you want gPodder to display an icon in your desktop's status notification area (for example, the System Tray on the Windows Taskbar). If this icon is present, then closing the gPodder window does not exit the application.

[edit] gpodder.net Preferences

gPodder.net is a Web service that helps you synchronize your podcast subscriptions across multiple devices, discover interesting new podcasts, and recommend your podcasts to others. Click the gpodder.net tab to set how gPodder interacts with gPodder.net.

Note: To use gPodder.net, you need to register for a user account first.

Synchronize subscriptions and episode actions: Check this box to merge the subscriptions on your computer or device with your subscription list on gPodder.net. These podcast subscriptions are now available to any other devices you sync with gPodder.net.

Username: Enter your gPodder.net username.

Password: Enter your gPodder.net password.

Device name: Enter a meaningful name for your computer, or keep the one gPodder.net assigns. Make sure the name is unique.

Replace list on server with local subscriptions: Click this button to replace the subscription list on gPodder.net with the list on your device.

Caution: Any podcast subscriptions on gPodder.net but not on your local computer will be lost.

[edit] Updating Preferences

Click the Updating tab to see gPodder's options for updating feeds and downloading new episodes.

Update interval: Drag this slider to choose the frequency that gPodder checks your feeds for new podcast episodes. This time period can be between 10 minutes and 12 hours. If you drag the slider all the way to the left, gPodder will not check for new podcasts automatically, and you will have to update them yourself.

Check for new episodes on startup: Check this box if you want gPodder to check for new podcast episodes when it first starts. Otherwise, gPodder waits the set interval before checking for updates.

Maximum number of episodes per podcast: Use this spin box to set the maximum number of episodes that gPodder keeps in each podcast feed. Once this maximum is reached, gPodder deletes the oldest episodes in the feed as new ones are added.

When new episodes are found: Use this drop-down list to choose what you want gPodder to do when it finds new podcast episodes on a feed. The available options are:

Do nothing - gPodder marks new episodes in the feeds as new, but takes no other action.
Show episode list - gPodder displays a window showing a list of all new episodes available for download. You can then choose the specific episodes that you want to download, ignore, or mark as old.
Add to download list - gPodder automatically adds all new episodes to the the download list under the Downloads tab in the main window. However, they are marked as paused, and you need to right-click on them and choose Download to get the.
Download if minimized - If gPodder is minimized, it will automatically add new episodes to the download list and download them. However, if the gPodder window is open on the desktop, then gPodder shows you a list of new episodes, as if Show episode list was chosen.
Download immediately - gPodder adds new episodes to the download queue and automatically downloads them.

[edit] Clean-up Preferences

Click the Clean-up tab to see gPodder's options for managing old downloaded podcasts.

Delete played episodes: Drag this slider to set the length of time before gPodder automatically deletes old podcasts. This time period can be between one and 30 days. If you drag the slider all the way to the left, podcast episodes will not be deleted automatically, and you will have to manage them yourself.

Also remove unplayed episodes: By default, gPodder will automatically delete played episodes but leave unplayed ones alone. Check this box if you want gPodder to clean up unplayed episodes as well. If you have chosen to delete played episodes manually, this option is not available.

Remove finished downloads from the downloads tab: Check this box if you want gPodder to clean up successfully completed downloads from the Downloads tab in the main window. If you leave this box cleared, then the Downloads tab lists every download gPodder has made since it was started, and does not remove then from the list until you remove them manually or quit the application.

[edit] Devices Preferences

Click the Devices tab to see gPodder's options for portable media player devices.

Device type: Choose the type of device from this drop-down list that matches your player. The available options are:

iPod - Choose this device if your media player is an Apple iPod, which requires special software (for example, iTunes) to manage media files.
Filesystem-based - Choose this device if your media player is treated like a simple USB storage device, and media files are added by copying them to a directory on the device.
MTP - Choose this device if your media player supports the Media Transfer Protocol (MTP) to manage media files.

Check the user documentation for your device if you're unsure what kind it is.

Mountpoint: Click this button to choose the mount point where your media player normally appears on your system. For example, on a Linux system this might be /media/iPod, or on a Windows system it might be drive F:.

After syncing an episode: Choose what you want gPodder to do after it transfers a podcast eposide to your player. The available options are:

Do nothing - gPodder simply transfers the file and takes no further action.
Mark it as played - gPodder transfers the file and marks it as already played.
Delete it from gPodder - gPodder transfers the file, then deletes it from the computer.

Remove played episodes from device: Check this box if you want gPodder to delete media files you have already played from your device when it synchronizes.

Only sync unplayed episodes: Check this box if you want gPodder to ignore episodes that have already been played, when synchronizing podcasts to your device.

[edit] Advanced configuration options

gPodder has many configuration options that are not all directly accessible through the Preferences dialogue box. Click the Edit config button to access the gPodder Configuration Editor, where you can see and change the full list of configuration options.

[edit] Everyday usage

[edit] Adding a Podcast

Manually add one at a time using Menu - Subscriptions -> Subscribe to new podcast and paste in the URL of the RSS feed.

[edit] Shortcuts for URLs

gPodder tries to be smart about what you enter in the URL field when adding podcasts to save you some typing:

You can leave out the leading "http://", as gPodder will automatically add it if the URL does not contain a URL scheme.

If the website has a correct <link> tag to the podcast RSS feed, gPodder can (most of the time) autodiscover the feed. So, instead of entering "feeds.feedburner.com/uncontrolledairspace", you can enter "www.uncontrolledairspace.com", and gPodder will figure out the feed URL (but see the next hint for another nice shortcut for FeedBurner URLs)

gPodder 2.1 and newer supports the "fb:" prefix for FeedBurner URLs, so that instead of having to type "feeds2.feedburner.com/podcastname", you can type "fb:podcastname", and gPodder will be smart enough to expand the URL correctly. If you know about other services where this makes sense, please get in touch, and we can add even more prefixes.

Another prefix that works is "yt:" for YouTube users. Use yt:username to add videos from YouTube user "username" to gPodder.

For Soundcloud feeds, you can use the "sc:" prefix to add SoundCloud users. Use sc:crunchtime to add music published by user "crunchtime" on Soundcloud.

[edit] Backing up the subscription list

The Podcasts menu provides an easy way to save your subscription list to an OPML file. The OPML file contains URLs for all the feeds you are subscribed to. It does not contain the status of episodes. You can re-import OPML files using the Podcasts menu. The OPML file format is a simple XML format that can be used to move feed subscriptions between different RSS-aware applications.

[edit] Importing subscriptions from iTunes

Export your iTunes podcast subscriptions to an OPML file. Copy it over to your device or computer and load it into gPodder with the Import from OPML file menu item.

[edit] Importing subscriptions from an OMPL file

Older version of gpodder have an Import from OPML file menu item and newer version may not. If you have the import option, you can select it, browse to your opml file and import it. No worries if you do not have this option as you can use the file url to handle the import.

Launch gpodder
Select Choose from a list of example podcasts on the gpodder startup assistant
Change the OPML/Search field to the file url for your opml file (e.g., file:///home/username/my.opml)
- You can open the opml file with your browser's "open file" to obtain the file:// url if you are unsure of it.
Select All podcasts and Add

At this point you should have a local list of subscriptions. You can push these up to gpodder.net via the Replace list on server with local subscriptions button on the Preferences : gpodder.net tab.

[edit] Listening to downloaded episodes

Most of the audio player applications available for the N8x0 do not support bookmarking (so you can resume playing a podcast from a saved point). Panucci is a resuming audiobook and podcast player written by the gPodder people that is available from Maemo Extras. Install the package and set the player variable to panucci (don't forget to set maemo_allow_custom_player, as stated above).

[edit] Appending episodes to the current playlist

Most applications will stop the current song/episode and start playing the selected episodes when clicking on Play. You can avoid that by setting a custom command in the settings dialog:

Application	Command	Remarks
Aqualung	`aqualung -N0 -E`	This option loads the files, but does not start playback automatically, you can try adding the -L command for that, but that tends to start playback on the last one loaded. But once the first file is playing, you can load up your play-list from gPodder for hours of listening enjoyment.
VLC 0.9.4	`vlc --playlist-enqueue --started-from-file` (Linux) `"C:\Program Files\VideoLAN\VLC\vlc.exe" --playlist-enqueue --started-from-file` (Windows)	This will Que up the file and play the first one and you can add more while your listening. You may have to click your play button, but once playing it ought to continue to play the created playlist.
SMPlayer	`smplayer -add-to-playlist %F`	Adds thefiles to the current SMPlayer playlist

[edit] Synchronising podcasts to MP3 players

Here is how it works for an iPod. Do generic MP3 players work the same way?

Plug your iPod in to a USB port on your computer. The flashing "no entry" sign and the message "Do not disconnect" will appear.
The iPod may be auto-mounted to some mount point, typically in /mnt or /media. If not, you will need to mount it yourself: messages in the system log (/var/log/messages or similar file) will tell you what device it was detected as, for example /dev/sdb2. You can then mount it as root by typing:
```
mount -t vfat -o umask=0000 /dev/sdb2 /media/ipod
```
where /media/ipod is a mount point (empty directory) that you have created. To allow it to be mounted by users, you can add a line to /etc/fstab:
```
LABEL=IPODNAME  /media/ipod     vfat    users,umask=0000  0 0
```
where IPODNAME is the volume label for the iPod hard drive.
Check it is mounted: you should be able to list the content of the mount point directory, and it will contain subdirectories
```
Calendars/  Contacts/  iPod_Control/  Notes/
```
Start gpodder, and tell it the mount point: PodCasts -> Preferences -> Advanced, edit setting ipod_mount or mp3_player_folder.
Synchronize the gPodder podcast database with your player: Podcasts -> iPod -> Synchronize or Device -> Sync.
Unmount the iPod. At the command line type
```
eject /media/ipod
```
(assuming your player was mounted on /media/ipod). This which will unmount the iPod and close the connection so that the "Do not disconnect" message disappears and the iPod changes into USB charging mode (you can use the iPod's menus in this mode). On older versions of Linux the eject command may not be available: you can type
```
umount /media/ipod
```
Wait for the shell prompt, then unplug your iPod. It is safe to do so, even though the "Do not disconnect" message is still present.

[edit] Custom file names

You can use custom file names when synchronising. This makes browsing files on your device much more convenient.

The default value for the custom filename field is {episode.basename}. This will work for most podcasts. However, occasionally you may find a podcast where the producers don't provide unique information in the tags, which can result in multiple episodes being given the same name (e.g. podcast.mp3), and thus overwriting one another on synchronisation. One work around to this is to include the {episode.published} data. Multiple fields can be concatenated, e.g.: "{episode.basename}_{episode.published}" which will result in files of the form "podcast_20090114.mp3"

[edit] Advanced topics

[edit] Command-line interface

gPodder includes a command-line interface. The command is called gpo. You can get a list of possible actions by running the command without any parameters.

[edit] Using a HTTP proxy server

You can use a HTTP proxy server for downloading episodes and feeds. Newer versions of gPodder do not provide a way to do so in the GUI, but respect the environment variable http_proxy. How to set the http_proxy environment variable in different operating systems is described here:

Setting http_proxy in Windows, Mac OS X and Linux/Unix

On Linux and Unix-like systems you can also create a short shell script if you want to use a proxy for gPodder, but don't want to use a proxy for other applications:

   #!/bin/bash
   http_proxy=http://username:password@hostname:port
   export http_proxy
   gpodder

[edit] Using Yahoo! Pipes to fix feeds

There might be some problems with feeds (see the related bug report) - to fix it, you can try to use Yahoo Pipes:

Create a new pipe with the problematic feed as source
Make no transformation
Use the RSS output of the resulting pipe in gPodder

See a screenshot of the pipe source to get an idea of how it should look like.

[edit] Reporting download problems

If you have got problems with episode downloads, please follow the instructions on the page about reporting download problems.

[edit] Time stretching (making playback slower or faster)

Making playback slower or faster is generally called time stretching. There are certain algorithms that maintain the original pitch so that your favorite podcast speaker doesn't sound like donald duck after doing the processing. It is a great time saver to listen to podcasts with a faster playback speed. You easily listen to most speakers with 45% speed up and after your used to it, even 70% speed up is understandable.

The audio files can be processed by gPodder before transferring them to a portable device. The following is a script for speeding up a single mp3 file by 45%:

#!/bin/bash
# mp3faster - script for making mp3 playback faster with soundstretch
#
# debian/ubuntu package requirements
# apt-get install mpg321 soundstretch lame libid3-3.8.3-dev
#
# rhel/centos/fedora package requirements
# yum install mpg321 soundtouch lame id3lib
#
# sample usage for converting all mp3 files in a directory structure:
# find -name "*.mp3" -print0 | xargs -0 -i mp3faster {}
#
# decode mp3 to wav file
mpg321 --wav "$1.wav" "$1"

# the above decoding technique doesn't always work, and can sometimes 
# create a wav file that plays back too fast. Seems to happen with mp3 files that
# have a low bitrate (< 80kbps). Using the lame alternative below get's around this.

# alternative #1 to decoding an mp3 to wav
# lame --decode "$1" "$1.wav"
# alternative #2 to decoding an mp3 to wav
# mpg321 -b 10000 -s -r 44100 $1 | sox -t raw -r 44100 -s -w -c2 - "$1.wav"
# process file with soundstretch
soundstretch "$1.wav" "$1.fast.wav" -tempo=+45
# encode mp3 file
lame --preset fast medium "$1.fast.wav" "$1.2.mp3"
# copy id3 tags from old file
id3cp "$1" "$1.2.mp3"
# remove temp files
rm "$1.wav" "$1.fast.wav"
# rename original mp3 file to .bak extension
mv "$1" "$1.bak"
# rename processed mp3 file to original name
mv "$1.2.mp3" "$1"

Using the post-download script hook

gPodder can execute an arbitrary script after a download has finished. The script file name is set in the advanced configuration editor variable cmd_download_complete (available since gPodder 0.12.1). Here's an example script for processing a MP3 podcast for faster playback after it has been downloaded (making use of the mp3faster script from above):

#!/bin/bash
LOGFILE=~/.gpodder_download.log
date >> $LOGFILE
echo "url: $GPODDER_EPISODE_URL"  >> $LOGFILE
echo "title: $GPODDER_EPISODE_TITLE"  >> $LOGFILE
echo "filename: $GPODDER_EPISODE_FILENAME"  >> $LOGFILE
echo "pubdate: $GPODDER_EPISODE_PUBDATE"  >> $LOGFILE
echo "link: $GPODDER_EPISODE_LINK"  >> $LOGFILE
#echo "desc: $GPODDER_EPISODE_DESC"  >> $LOGFILE
ext=${GPODDER_EPISODE_FILENAME##*.}
if [ "$ext" == "mp3" ]; then
	echo "Converting file" >> $LOGFILE
	~/bin/mp3faster "$GPODDER_EPISODE_FILENAME" >> $LOGFILE 2>&1
fi

Time Stretching on Windows

The following batch file can be used for time stretching on Windows (instead of the above two bash scripts). Note that this batch file deletes the original MP3 file (replacing it with the stretched version), it does not copy any MP3 tags to the new file (so all tags will be lost), and soundstretch and lame must be installed. Name this file speedup.bat and set cmd_download_complete to point to this file. In gPodder 2.14, there seems to be a problem with cmd_download_complete that causes every other download to fail when using this script. If you run into this problem, consider using the script below instead ("Alternate Time Stretching on Windows").

REM speedup.bat - script for making mp3 playback faster with soundstretch
REM soundstretch and lame must be installed first.
REM deletes the original .mp3 and replaces it with the processed version
REM does not copy any tags from the original .mp3 to the processed version

REM exit if it's not an .mp3
set FILE=%GPODDER_EPISODE_FILENAME%
if not %FILE:~-3%==mp3 exit

REM decode mp3 to wav file
lame --decode "%FILE%" "%FILE%.wav"

REM process file with soundstretch
soundstretch "%FILE%.wav" "%FILE%.fast.wav" -tempo=+50 -speech

REM encode mp3 file
lame --preset standard "%FILE%.fast.wav" "%FILE%.2.mp3"

REM clean up - delete original .mp3, replace with processed .mp3
del "%FILE%"
del "%FILE%.wav"
del "%FILE%.fast.wav"
move "%FILE%.2.mp3" "%FILE%"

Alternate Time Stretching on Windows

This alternate time stretching script will time-stretch EVERY .mp3 file in your gPodder downloads folder - so this script is only useful if you listen to (and delete) all the .mp3 files in your downloads folder, before you download more files.

This can be used as a stand-alone program, and in theory it can be used with cmd_all_downloads_complete (but in gPodder 2.14, there seems to be a problem with cmd_all_downloads_complete that causes this script to get started multiple times). If you have a slower system and you don't want this script to take over the CPU, consider starting the script with priority /LOW using the START command.

As with the script above, this batch file deletes the original MP3 file (replacing it with the stretched version), it does not copy any MP3 tags to the new file (so all tags will be lost), and soundstretch and lame must be installed first. In the script, replace C:\gPodder\gpodder-2.14-win32\downloads with the path to your gPodder downloads folder.

REM Time-stretches EVERY .mp3 file in your gPodder downloads folder!
REM Soundstretch and lame must be installed first.
REM Deletes the original .mp3 and replaces it with the processed version.
REM Does not copy any tags from the original .mp3 to the processed version.
REM Replace C:\gPodder\gpodder-2.14-win32\downloads with
REM   the path to your gPodder downloads folder before running!

for /R "C:\gPodder\gpodder-2.14-win32\downloads" %%F in (*.mp3) do (

REM decode mp3 to wav file
lame --decode "%%F" "%%F.wav"

REM process file with soundstretch
soundstretch "%%F.wav" "%%F.fast.wav" -tempo=+50 -speech

REM encode mp3 file
lame --preset standard "%%F.fast.wav" "%%F.2.mp3"

REM clean up (delete original .mp3, replace with processed .mp3) 
del "%%F"
del "%%F.wav"
del "%%F.fast.wav"
move "%%F.2.mp3" "%%F"

)

[edit] Changing the downloads folder location

In gPodder 3.x, the default download location is $GPODDER_HOME/Downloads/. Here are the default values of $GPODDER_HOME depending on the operating system:

Linux/FreeBSD/Mac OS X: ~/gPodder/
Windows: gPodder folder in the user's home directory
MeeGo 1.2 Harmattan: /home/user/MyDocs/gPodder/

If you want gPodder to download files in another directory, change the GPODDER_HOME environment variable. Make sure to also move the database and associated files from the old to the new home directory of gPodder.

These are the default download locations for gPodder 2.x:

Linux/FreeBSD/Mac OS X: ~/gpodder-downloads/
Windows: downloads (in the gPodder folder)
Maemo 4: /media/mmc1/gpodder/ or /media/mmc2/gpodder/
Maemo 5: /home/user/MyDocs/Podcasts/

You cannot change the download folder using gPodder's GUI (see bug 566), but you can do so manually with the steps provided here.

[edit] On Linux/FreeBSD/Mac OS X (gPodder 2.x only)

To change the download folder, first close down gPodder if it's opened. Then, open the file ~/.config/gpodder/gpodder.conf with a text editor. Under Gnome, you can use Alt+F2 to open the Run Application dialog and enter:

gedit .config/gpodder/gpodder.conf

This should open an editor window with the gPodder configuration file. You now have to search for the line starting with download_dir = and change the value to where you want to move the folder. Save the file and close the editor. Now move the folder to its new location, and after that, re-start gPodder. gPodder should now use the new download folder.

[edit] On Windows (gPodder 2.x only)

You cannot change the download folder under Windows, but you can move the application folder wherever you like, and the downloads folder will automatically move with it.

You can however, create a symlink (junction) between the downloads folder and the folder you want your podcasts stored it. Windows 7 has native support for this, using the mklink command, users of older Versions (starting with XP) should be able to use the Link Shell Extension freeware tool to accomplish this.

Let's pretend you installed gpodder in C:\Program Files\gpodder and want to store your podcasts in D:\Music\Podcasts. First of all, back up all the contents of the downloads folder in the gpodder directory or move it into the new directory right away. Then delete the downloads folder (again, make sure you really backed up anything in there!)

In Windows 7, open the command shell (cmd.exe), using Administrator privileges (either choose run as Administrator from the context menu, or click cmd.exe holding Shift+Ctrl). Type:

mklink /J "C:\Program Files\gpodder\downloads" "D:\Music\Podcasts"

This will create a connection between these two folders and will actually store the downloaded files in D:\Music\Podcasts

[edit] On Maemo 4 (gPodder 2.x only)

For Maemo 4 (N800 and N810), you can choose between the internal and external memory card slot. By default, the internal slot will be used. If you want to move the downloads folder, first make sure gPodder is not running. Then use the file manager to move the "gpodder" folder on your memory card to the other memory card's root directory (e.g. directly below the "memory card"). After that, restart gPodder, and it should automatically detect that you moved the download folder and use it for future downloads.

[edit] On Maemo 5 (gPodder 2.x only)

You can follow the instructions for "On Linux/FreeBSD/Mac OS X" above if you want to change the download folder location, but you are encouraged to leave the download folder at its default setting for Maemo 5.

[edit] Getting support

See the main page for a list of support options and self-help resources. You can also find links to the mailing list and the IRC channel there, so you can get in touch with us.