Requirements

download the distro from here.

gigi will run on linux platforms with python 2.x and gtk installed. You’ll need:

get_iplayer version 2.83 or later. To get that version you may need to add the get iplayer ppa to your update manager.

configobj version 4.7 or later (in the ubuntu repositories as python-configobj; or “pip install configobj” if you have pip)

pygtk version 2.2 or later (probably there by default in any recentish version of ubuntu)

And optionally:

python-notify (in the ubuntu repositories as python-notify; may be there by default)

In ubuntu you can install the packages you may be missing from the command line with:

sudo apt-get install get-iplayer python-configobj python-notify

At the moment gigi will not run on Windows or Mac. Getting the latter to work is probably near-impossible (gtk can only be made to work on Macs with great effort, if at all). A Windows version may be possible, if there’s demand (but for instance select in python doesn’t work with pipes on windows, which is embarrassing ’cause that’s how output from get_iplayer gets into gigi).

Back to top

Installation

Extract all files from the distribution archive, preserving its directory structure.

Make sure all .py files are executable.

Run install.py.

It will create the gigi configuration directory (~/.gigi unless you’ve used the --config-directory or --c option) and copies gip.conf, gigi.conf, categories.conf and channels.conf into it.

If your get_iplayer configuration directory (normally ~/.get_iplayer) contains a gigi.conf (from the previous version of gigi) or giplayer.conf (placed there by giplayer or giplayer-ext), it will copy relevant settings from it to your new gigi.conf and gip.conf. If you don’t want settings from conf files in the get_iplayer configuration directory to migrate to the new gigi settings, delete, rename or move those files (gigi.conf and/or giplayer.conf) before running install.py.

gip.conf determines what options are used when gigi invokes get_iplayer. On installation it will be tailored to conform to your get_iplayer user preferences, if there are any, and to get_iplayer defaults otherwise.

By default ubuntu doesn’t show icons on menus and buttons. gigi can. If you want to see them, do this in a terminal:

gconftool --set /desktop/gnome/interface/menus_have_icons --type bool true

gconftool --set /desktop/gnome/interface/buttons_have_icons --type bool true

Back to top

Running gigi

Double click on the file gigi.py wherever you’ve put it.

Or, in a terminal, switch to the directory in which it lives and enter run ./gigi.py [options]

You can run only one instance of gigi at a time

Back to top

Options

Back to top

The GUI

There are alt key shortcuts for menus, as well as for the Search, Download and Play buttons, and the Describe and Cancel all/Remove all buttons if and when visible.

If you hit Return when the cursor is in any of the programme, category or channel textboxes, it has the same effect as clicking the Search button.

If you hit Return having made a selection in the search results list, it has the same effect as clicking the Download button.

Hitting F1 at any time will bring up context-sensitive help relating to whatever widget currently has focus.

There’s a right click menu on a selection in the search result list.

Back to top

Searching

Any search will be subject to the constraints specified in the Search menu, namely the type(s) of programme and fields searched, and whether previously downloaded programmes are included in results.

The programme textbox:

All programme names and/or episodes become auto-completion suggestions in the search field. Only those names and/or episodes available for the types chosen on the search menu, and in the channel(s) and category(ies) selected are offered. Also offered will be names with initial articles (“a”, “an”, “the”) removed, and episodes with initial numbering (e.g. “3.”) removed.

Text entered in the programme textbox can be a regular expression.

Suppose you want to create a regular expression of the form <programme name>|<programme name>? How do you use the auto-completion to come up with the second programme name, when auto-completion only works in an empty text box?

To enter multiple auto-completed entries (after a fence or bar character, for instance), type a Page Up.

Everything in the Search box will be added to a label above it.

(If there's text in the label above the programme textbox, there will also be a button that lets you undo the process, transferring text from label back to textbox. You can get the same result with Page Down).

You can then start a new auto-completed entry in the programme textbox.

When you search, everything in that label will be prefixed to everything in the programme textbox. Each alternative in the combined text will be tested to see if it’s a complete programme or episode name; if it is it will be wrapped in the regex start (“^”) and end line (“$”) indicators.

If there's been a successful search (i.e. one that returns at least one matching programme), the entry in the programme textbox as of that search will be saved on programme exit and loaded when it’s restarted.

Back to top

The category textbox:

The hierarchy of categories used by the BBC to classify iPlayer programmes can be accessed from the button next to the category(ies) textbox (or by hitting alt-M when cursor is in the category textbox).

If you left click a leaf category in the hierarchy:

• If the textbox is empty or contains a category or categories, the category chosen replaces it
• If the textbox contains text ending in an alternative operator (“|”), the category chosen is added on the end of the text to make an alternative

If you right click on any category:

• You can insert the category and all its containing categories, combined into a regex with the categories in alphabetical order (which is how iPlayer categories are organised)
• If the category text box already contains text, you can combine the category you've right clicked on into the existing text as a regex of alphabetically ordered categories
• If the category text box already contains text, you can combine the category you've right clicked on and all its containing categories with the existing text into one regex

If there's been a successful search (i.e. one that returns at least one matching programme), the entry in the category textbox will be saved on programme exit and loaded when it’s restarted.

Back to top

The channel textbox:

Back to top

Search results

Every TV programme may be available in up two three versions; default, signed, and/or audiodescribed. You can choose to see any or all of those versions (so there may be as many three items in the search results list for a single programme). If signed and/or audiodescribed versions are listed, they are coloured, and distinguished by ‘S’ or ‘A’ in the first column of the list box.

You can choose which versions you want to see in search results in the video sub-tab of the get_iplayer tab in the preferences dialogue.

There’s a right click menu on a selection in the search result list.

Programme descriptions

Programme descriptions (including an image and a button to take you to the programme’s website) pop up in the right hand pane. However, they won’t appear if:

• More than one row (or none) is selected in search results
• A row is selected for less than a second (or the time set in the descriptions, preferences sub-tab of the gigi tab, preferences dialogue).
• This could happen if you’re navigating up and down the search list with arrow or page-up/page-down keys.
• The pane divider is far to the right, to make the description panel disappear or become very small.

The descriptions, preferences sub-tab of the gigi tab lets you disable the automatic fetching of descriptions after a number of seconds.

If you do that a Describe button will appear above the right hand pane, and you have to hit that to get a programme description.

Back to top

Downloading

If you cancel a download and then select the same programme and start it later, generally the download will pick up where you left off, providing you don’t delete the *.partial.* file produced by the interrupted download.

You can select more programmes to download while previously launched downloads are still in progress.

You can do another search and select and download files from the results while downloads are in progress.

There are a few differences between default downloading behaviour of gigi and get_iplayer:

• Normally get_iplayer will not download programmes that its history says have previously been downloaded. gigi overrides this restriction by inserting the --force option in directions to get_iplayer to download. You can override this by adding --noforce to your get_iplayer preferences.
• Normally get_iplayer will not overwrite files that already exist. gigi overrides this restriction by inserting the --overwrite option in directions to get_iplayer to download. You can override this by adding --nooverwrite to your get_iplayer preferences.

File naming

File names for downloads are governed by settings in the file tab of the preferences dialogue.

Back to top

Playing a programme

The Play button is only responsive when a single programme is selected in search results.

If you hit it, or alt-P, the media player selected in the player selected in the player tab of the preferences dialogue (by default on first run: vlc) starts streaming the selected programme, and the Play button becomes the Cancel Player button. Play stops when you close the player or hit Cancel Player.

Back to top

The file menu

From the File menu you can:

Back to top

The archives menu

You can get programmes listed in the BBC 4 collections and BBC archives.

If you pick “collections” or “subjects” within the BBC archive submenu, you’ll get a dialogue with a list of categories; once you pick a category, you’ll get a dialogue with a list of collections or subjects.

The BBC 4 collections menu item takes you directly to a dialogue with a list of collections.

Picking a collection will produce a list of programmes in the collection in the gigi programme list; you can then download or play them as usual.

(Some collections e.g. Dad’s Army have no radio or TV content; you’ll just get a message to that effect if you select such a collection.)

You may experience delay while the combo boxes giving you your choices are constructed.

The “people” item within the BBC archive submenu produces a list of people in the gigi listbox and changes the Download button to the Go button. Clicking on Go with one person selected will produce a list of programmes related to that person.

Columns in the listbox will be renamed or hidden for particular types of archive. The header of the first column will be changed to reflect the archive, collection, subject, person etc you’re looking at.

Selecting any one item in the listbox will show details about that programme in the description panel.

None of the controls that apply to searches (i.e. anything on the Search menu, all the controls above the listbox) have any effect when navigating through the archives menus.

Back to top

The edit menu

In addition to launching the Preferences dialogue, you can perform several operations on gigi’s settings. You can restore them to installation defaults; force a synchronisation of gigi settings with get_iplayer preferences; and force a synchronisation of gigi settings with both get_iplayer preferences and its default options.

Back to top

Preferences

The preferences dialogue can be activated from the Edit menu.

It has two top-level tabs: one defines defines settings that affect gigi behaviour; the other settings that change options sent to get_iplayer.

Options used by get_iplayer are also determined by several menus that include checkboxes and/or radiobuttons.

The gigi options tab:

saving menus tab:

The Quality, Search and File | Choose preset menus feature radio buttons and checkboxes. On exit from gigi, or when you switch away from a preset you’ve modified, you can choose, for each menu to which you’ve made changes, whether to:

• always save changes silently
• never save changes
• ask each time whether to save changes or not

threads, autocompletion tab:

threads:

set the maximum number of downloads to fetch at once (defaults to 3; probably best to avoid the ire of the beeb by keeping this number low)

set the maximum number of programme descriptions to fetch at once (ditto)

reset gigi.conf to default (affecting gigi options controlling its own behaviour, i.e. all settings on sub-tabs of the gigi options tab)

autocompletion:

programmes names and episodes can be acquired for autocompletion within the programme textbox. You can choose whether this should happen automatically (on startup and when gigi configuration changes; manually, when you hit the button next to the programme textbox; or never.

descriptions, preferences tab:

descriptions:

choose which level of description to display (full, short, medium; full, the get_iplayer default, is also the gigi default)

choose whether to show descriptions after a timeout, or instead to show a Describe button

set the length of timeout (0 to 10 seconds; zero seconds if you want descriptions to show without delay)

overriding preferences:

action to take if you override a get_iplayer user preference (or preference set in a current preset)

determine when gigi syncs with get_iplayer (and what happens when it does):

• every time gigi starts (which will add a few seconds to gigi startup time)
• when gigi is upgraded (when it would be normal to allow a check on get_iplayer preferences, because they might conflict with new gigi settings)
• whenever a preset is chosen (you probably always what the preferences saved in the preset to be integrated into gigi settings, otherwise there’s not much point in loading a preset)
• or only when you choose one of the sync options from the Edit menu

In each case, you can choose what happens if there’s a conflict between an existing gigi setting and a get_iplayer preference: always leave the existing gig setting; always change the setting to match the get_iplayer preference; or ask each time.

Back to top

The get_iplayer options tab:

audio tab:

choose the directory in which to save radio downloads. Defaults to ~/iplayer/radio.

choose radio download format (radio buttons for “default”/“force mp3”)

specify custom radio download quality (which can then be selected from the Quality menu)

choose the directory in which to save podcast downloads. Defaults to ~/iplayer/podcast.

choose the programme to use for audio playback (a combo allowing selection of vlc/mplayer/ffmpeg, and a “use gip preference” checkbox if a preference is defined)

specify custom radio playback quality (which can then be selected from the Quality menu)

video tab:

choose which versions of TV programmes you want to see (the gip default or preference; default, signed or audiodescribed).

choose which alternate versions you want to see only if your first choice of versions isn't available (for instance, you might choose to see signed or audiodescribed versions, but only if the default was no longer available).

choose the directory in which to save TV downloads. Defaults to ~/iplayer/tv.

choose download format (radio buttons for mp4/flv)

choose whether to download/play subtitled version (radio buttons; if a gip preference is in force the relevant button is labelled accordingly)

specify custom tv download quality (which can then be selected from the Quality menu)

choose the programme to use for video playback (a combo allowing selection of vlc/mplayer/ffmpeg, and a “use gip preference” checkbox if a preference is defined)

specify custom tv playback quality (which can then be selected from the Quality menu)

file tab:

In separate subtabs for iplayer and archive programmes there are the following options governing how file names are created for downloaded files.

choose whether to construct filenames using only the prevailing get_iplayer defaults or user preferences. If you choose that all other options on the subtab are disabled. If you don’t choose to disable them, there are widgets to:

choose what to do with whitespace in file names (a combo box selection where you can choose to convert to underscore; leave alone; or remove and convert to camel case)

independently of what you choose to do with whitespace, choose whether to:

• allow non-ascii characters
• allow punctuation (other than underscore, hyphen and full stop)
• if allowing punctuation, allow only os friendly characters only

choose which get_iplayer substitution parameters to include in file names.

Toggle a substitution parameter between used and unused by double clicking on it.

Change the order of substitution parameters by dragging.

You can add a prefix to go before each substitution parameter in use by editing the first column in the substitution parameter listbox.

From the right click menu on a prefix to make its appearance dependent on whether the substitution parameter has a value for any given programme.

Note that unlike in the get_iplayer --fileprefix option, you can have whatever text you want as an optional prefix.

From the same menu you can propagate the prefix through other substitution parameters.

You can choose the directory in which to save programmes of unknown type. It’s sometimes difficult to figure out if an archived programme is radio or tv; if that can’t be determined, it will be saved to the directory you specify here. Defaults to ~/iplayer/unknown.

You can choose whether to allow duplicate files. You can always prevent them from downloading, always allow them or ask each time a duplicate is about to be saved.

You can choose whether to purge old files regularly (yes, no, ask every so many days).

Unless you choose “no” you can set how many days is considered “old”.

If you choose “ask” you can set how often you are asked.

Back to top

Menus determining get_iplayer options:

Several menus include checkboxes and/or radio buttons whose values are stored along (and possibly saved) with gigi preferences affecting get_iplayer options.

Back to top

The Quality menu:

There are separate radio button submenus to set the quality of radio downloads; tv downloads; playing a radio programme; and playing a tv programme (podcasts have no quality settings; they’re plain mp3 files, not streams).

Each quality menu item has a tooltip showing the modes it defines.

Each submenu includes a “use gip default” or “use gip preference” checkbox, also with its modes tooltip. Selecting that checkbox disables all other items in the submenu.

The Search menu:

Choose which types of programme are searched for (by default only tv is selected). There’s also a “use gip default” or “use gip preference” option, with a tooltip displaying what types that implies.

Choose which fields in programme descriptions are searched (any combination of <name>, <episode>, <description>, <categories> checkboxes). There’s also a “use gip default” or “use gip preference” option, with a tooltip displaying what fields that implies.

Choose whether previously downloaded programmes are hidden in search results (by default on first run not checked).

Any changes made to the Search or Quality menus (which are made up entirely of checkboxes and radiobuttons) might only be meant to be temporary. For instance, you might as a one-off want to check TV programmes instead of radio, or set the quality for a particular radio programmes to high.

Therefore if you make changes to any of those menus, you will be asked if you want to save those changes when gigi exits. If you prefer to have your menu changes saved silently, or not saved at all, there are checkboxes for that in the saving menus tab of the preferences dialogue.

Back to top

get_iplayer user preferences in gigi

gigi settings (normally stored in the the ~/.gigi directory) can be synced with get_iplayer default options and user-defined preferences. This happens automatically when you first run gigi, or upgrade from version 0.81beta. You can make it happen at any time from items on the the Edit menu, and control when it happens by making choices on the the gigi tab of the preferences dialogue (e.g. choosing whether to re-sync with get_iplayer every time gigi starts, or every time it’s upgraded.

In most cases, where there’s a gigi setting which allows a get_iplayer default option or user-defined preference to be used, there’s a “use gip default/preference” radio button or checkbox in the get_iplayer tab of the preferences dialogue, and on submenus of the Search and Quality menus.

special cases affecting the get_iplayer tab of the preferences dialogue:

download formats for TV and radio: In the preferences dialogue there are radio button pairs for each type of download, which govern the presence or absence of a get_iplayer option (--aactomp3 for radio MP3s; --raw to produce TV flvs). When gigi is synced with get_iplayer preferences, gigi settings are altered such that the appropriate radio button is chosen when any of these pairs is displayed. So if e.g. you have --raw as a gip preference, the appropriate gigi settings will be altered so that the “flv” radio button in the tv settings section of the preferences dialogue will be selected.

destination directories for downloads: Associated with each directory chooser (one each for radio, podcasts, tv and programmes of unknown type) there’s a “use gip default” or “use gip preference” check box.

• If unchecked, the directory you specify in the associated directory chooser will be stored as your preferred directory, If it doesn’t exist it which be created on first download, or when the preferences dialogue is opened, whichever comes first
• If checked, the associated directory chooser will be disabled, and its value ignored
  • The checkbox has the label “use gip preference” if there’s a gip option in force (via user preferences or a preset) that can be used to specify an approprriate directory; e.g. --outputtv or --output for the tv directory chooser; --outputpodcast or --output for the podcast directory chooser, etc.
  • The checkbox has the label “use gip default” if there’s no relevant gip option. If you check such a box (not recommended), downloaded files will end up in $HOME if gigi has been started from a launcher; if its been started from a terminal, they’ll be saved in the current working directory.

special cases affecting the Search menu:

hide previously downloaded programmes: A submenu of the Search menu to do with whether previous downloaded programmes appear in searches. It encapsulates the presence or absence of the get_iplayer option --hide.

get_iplayer presets in gigi

When you select a get_iplayer preset from the file menu, gigi settings will be reevaluated to make them compatible with the user preferences carried by the preset. If you change gigi settings via menus or the preferences dialogue when a preset is in force, those settings will apply (possibly overriding preset options); but they will not be saved when you exit gigi, change presets, or revert to gigi operation without a gip preset.

A preset contains all gip options set via --preset=xxx --prefs-add, which override or add to those set via --prefs-add. Equivalently choosing a gip preset in gigi applies all gip options found in that preset to gigi, which override or add to those set via gigi.

If you choose a preset, all further interactions with get_iplayer will be with that preset in force. That’s achieved by altering the currently active preferences within gigi, as follows:

• gigi determines what gip options are included in the preset e..g. --output). For each such option,
• it determines which, if any, gigi preference(s) might conflict with with that option (e.g. the output directories set for each media type in gigi preferences).
• it then sets the “use gip default” or “use gip preference” alternative for that gigi preference.

You can also select a get_iplayer preset using a gigi command line option.

If you exit gigi with a preset selected from the file menu (but not if you’ve chosen a preset using the gigi command line option), you will normally be asked if you want to start gigi with the same preset next time.

If you want to save an altered preset, you can save your current gigi configuration to a preset from the file menu.

Latest version (0.91 beta) of gigi here.

Back to top

Back to home