Skip to content

hedgehog.1.ronn

Latest commit

 

History

History
786 lines (601 loc) · 33.1 KB

hedgehog.1.ronn

File metadata and controls

786 lines (601 loc) · 33.1 KB

hedgehog(1) -- podcast player and organizer

SYNOPSIS

hedgehog [--h|--help] [--no-mouse] [--no-pidfile] [--no-mpris] [-V*|*--version] [--config-path ] [--data-path ] [ ...]

DESCRIPTION

Hedgehog is a podcasts player and subscriptions management software that works within a terminal. Its features include:

  • subscribing to RSS feeds and managing subscriptions;
  • viewing and automatically updating the list of episodes from each feed;
  • keeping track of the episodes' state: whether you played an episode, did you finish listening to it or not, remembering when the playback stopped;
  • playing episodes and controlling its playback: play/pause, seek, control volume, etc.;
  • searching for feeds online and subscribing to them;
  • importing and exporting the list of feeds from/to other podcast management software via OPML documents.

The main interface of Hedgehog contains two panes: the list of feeds you are subscribed to (along with two special feeds with all episodes and with only new episodes) and the list of episodes within the selected feed. You can navigate between different panes using arrow and Tab keys or using a mouse cursor if your terminal emulator supports it. To start the playback of an episode, you can either select it and press Enter or double-click with a left mouse button.

See [KEY MAPPING][] section of this manual for the list of default keybinding which can be reconfigured, and commands section for the list of all commands that Hedgehog supports.

OPTIONS

  • --no-mouse: Disables the capacity of Hedgehog to read and handle mouse input. If not present, you can select list items, start and control playback, change the cursor position in the command entry field, etc., but you won't be able to select text in the terminal window.

  • --no-pidfile: By default, Hedgehog prevents two or more instances of the program from running at the same time to prevent inconsistencies in the displayed data. This flag prevents this behavior. Note that multiple instances are allowed to be executed for different data directories.

  • --no-mpris: Disables Hedgehog's support for MPRIS protocol. This protocol allows third-party software to observe the state of playback and control it by sending messages through DBus. Note, that not all platforms support this functionality Hedgehog may be compiled without it. In such cases, this option won't be present.

  • --data-path: Specifies the path from where episodes database, commands history and some other files will be read. The default is ~/.local/share/hedgehog/ on UNIX-compatible platforms and %APPDATA%/hedgehog on Windows. This location can be backed-up and copied to another system.

  • --config-path: Specifies a path or a set of paths where Hedgehog will search for the configuration files: rc files and themes. These paths extend the set of default paths. For more information on configuration, see the [CONFIGURATION][] section of this manual.

  • export : A sub-command for exporting the list of podcast feeds managed by Hedgehog in OPML format. This can be later imported into nother podcast management programs. is a path to an XML file where the exported data will be written or a dash (-) in which case the exported data will be written to standard output.

  • import : Adds the set of the podcast feeds to the database. Episodes from these feeds will be fetched on the next launch. Duplicate feeds will be ignored. is a path to an XML file in OPML format that will be read or a dash (-) in which case the data will be read from the standard input.

COMMANDS

You control Hedgehog TUI by issuing commands either directly (by pressing :, entering the name of a command and its arguments, and submitting it with the Enter key) or indirectly, by pressing a key combination mapped to a specific command. There are few exceptions, such as actions performed with a mouse or through the MPRIS interface.

When entering commands manually, some keys have a special meaning. Hedgehog tries to follow established conventions. These keys cannot be remapped, and you can find their list in the [COMMAND ENTRY KEY MAPPING][] subsection.

The remaining of this section lists the supported commands and their description.

NAVIGATION

  • line first: Selects the first line in the current list.

  • line last: Selects the last line in the current list.

  • line page-up: Moves the selection up by an entire screen.

  • line page-down: Moves the selection down by an entire screen.

  • line move-by : Moves the selection down (if is positive) or up (if is negative) by the specific number of rows.

  • line scroll-by : Scrolls the current list down (if is positive) or up (if is negative) by the specific number of rows and keeps the selected row. If after scrolling, the selection is not visible, the closest visible row will be selected (with some margin from the edge of a screen).

  • focus : Sets the currently selected pane. The selected pane is highlighted in the UI and all line commands listed above affect the list contained in this pane. Possible values for are listed below.

  • log: Opens the list of errors. This command is a shorthand for focus log.

  • repeat-command: Executes the last manually entered command again. This does not affect commands that Hedgehog couldn't parse or the repeat-command itself.

  • quit or q: Exits Hedgehog.

is an argument used by some commands and it names the section of the UI that is currently selected and is ready to handle users' interaction. The possible values for are:

  • feeds: the list of feeds located on the right-hand side of the library view
  • episodes: the list of the episodes in a feed;
  • search: the list of search results. Search can be initiated using the search command. When this pane is selected manually, Hedgehog shows results from the previous search;
  • log: the list of errors that occurred during the current session, these errors include networking errors, configuration issues, etc.;

PLAYBACK

  • play-current: Starts playback of the currently selected episode from the position when the playback stopped before. If this episode was never played or if it was finished, the playback starts from the beginning.

  • stop: Immediately terminates playback. Playback then can be restarted only by selecting the episode again.

  • finish: Immediately terminates playback and marks the previously playing episode as finished.

  • pause: Pauses the playback. It can be then resumed using resume or toggle-pause commands.

  • resume: Resumes the playback from the current position.

  • toggle-pause: Toggles between playing and paused states. This command is equivalent to either pause or resume depending on the current state of the playback.

  • : If the playback is active, changes the current position in the stream to the specified . This action may cause a temporary break in the playback due to buffering. The paused status of the playback won't be changed by this command.

    is specified in seconds, minutes, and hours separated by a colon. Only seconds are required. For example 160, 2:40, and 0:02:40 are equivalent. Leading zeros are allowed.

  • seek : If the playback is active, changes the current position in the stream by the specified duration relative to the current position. The may be preceded by either + or - characters, which indicate whether the seek operation will be performed forwards or backwards.

  • rate : Changes the playback rate of the current stream. If the argument equals 1.0, the episode will be played at normal speed, any value less than 1.0 will cause the playback will be slowed down, and if the value is greater than 1.0, the playback will be sped up.

  • mute, unmute, toggle-mute: Changes the muted status for the playback. The muted status does not affect the current volume, when unmuting, the playback volume will be restored to the previous value. toggle-mute variant of this command toggles between muted and unmuted states.

  • vol-set : Sets the volume to the specified value. must be a number between 0 and 100.

  • vol-adjust : Changes the current volume by a specified amount. signed volume has the same unit as in the vol-set command: the range is -100 to 100.

SUBSCRIPTIONS MANAGEMENT

  • add : Adds a new subscription. Hedgehog will try to fetch the feed metadata and episodes list immediately after it finishes. Note, that must point to the RSS feed, Hedgehog will not try to determine the URL of the RSS feed from the HTML page's metadata.

  • delete: Removes the feed and all its episodes or a group depending on the item currently selected in the feed list sidebar. In cases when a group is deleted no feeds in this group are deleted, instead their group is unassigned. This action cannot be undone.

  • update [--this]: Updates the feed metadata and the episodes list. If new episodes are found in the feed, they will appear in the library marked "new". If --this attribute is specified, then only the currently selected feed will be updated. Otherwise, all feeds that haven't been disabled will be updated.

  • add-archive : Loades episodes from the RSS feed located at and adds them to the current feed. It's useful with some podcasts that offer two types of feeds: the one with a few recent episodes which can be fetched quickly and another with all episodes that may take some time to update.

  • enable, disable: Enables or disables the feed. If you disable the feed, then it won't be scheduled to be updated by neither the update command nor automatically on launch.

  • open-link feed, open-link episode: Opens the WWW URL specified in the feed or episode metadata respectively in the default browser.

  • hide: Hides the currently selected episode from the episodes list. Note, that it won't be deleted from the database. The hidden episodes aren't shown in the library by default. This can be enabled by issuing the command set hidden true.

  • unhide: Removed the hidden status from the currently selected episode. To issue this command, Hedgehog needs to be configured to show hidden episodes (using command set hidden true; it can be reverted by issuing set hidden false)

  • mark [--all] [--if ]: Changes the status of the episode. The can be either new, seen, or finished. By default, only the currently selected episode will be affected. If --all attribute is specified, then all episodes in the currently selected feed will be altered. In this case, it can be useful to update only a subset of episodes, for example, you may want to mark all new episodes in the new feed as seen. --if attribute specifies a precondition for such update. status-condition can be either new, seen, finished, started, or error.

  • reverse: Changes the order of episodes in the selected feed. By default, episodes are displayed in reverse chronological order (starting with the newest). This command changes this order for a single feed. This preference is saved in the database and will remain after the restart.

  • rename <new name>: Changes the name of a group or feed displayed in the sidebar that is currently selected. If the feed's name declared in the RSS feed changes, this change doesn't override the title set using rename command.

  • search or s : Starts the search session. When this command is issued, Hedgehog performs a search for podcast feeds online and search pane comes into focus.

  • search-add: Subscribes to the currently selected feed in the search pane.

  • add-group : Creates a new group and places it at the bottom of the feeds lists. Group names must be unique, meaning there cannot be more then one group with a given name.

  • set-group : Adds the currently selected feed into a group identified by .

  • unset-group Removes the currently selected feed from a group.

  • place-group : Changes the position of the currently selected group. is a non-negative integer indicating the place of a group in the list. place-group 1 will position the group at the very top immediately after the last feed which has no group assigned. place-group 2 will place the group immediately after. It's not possible to change the position of the feed without an assigned group.

CONFIGURATION

  • confirm [--default ]: Displays confirmation prompt and askes the user for confirmation. The will be executed only on an affirmative response. --default attribute specifies the default behavior, whether the command will be executed (if true) or not (false) when the Enter key is pressed.

  • exec : Reads the file at path and executes commands in it. Each command must be specified on a separate line; empty lines or lines containing only comments (starting with #) are ignored. All commands will be executed until the first failure or until the end of the file is reached.

    can be either absolute or relative. If is relative, Hedgehog will try to find a file in any of the paths specified in the list of data directories. See details in the [CONFIGURATION][] section of the manual.

  • set : Updates the property controlling how Hedgehog looks like and behaves. The list of properties is described in the [CONFIGURATION][] section of this manual.

  • msg [--info|--warn|--error]: Displays a in the status bar. It's displayed in a different color depending on the specified attribute. If the --error attribute is provided the message will also appear in the errors log (available using log command).

  • map : Maps to a specific key combination so that this command is executed when the key combination is pressed. You can have different commands executed depending on the state of Hedgehog using conditional commands described below.

  • unmap : Removes the key mapping crated using the map command.

map and unmap commands accept argument specified in the format similar to the one used by vim and some other software. Key specification consists of zero or more modifiers followed by the key's name. Allowed modifier are:

  • S or Shift for the shift key,
  • C, Ctrl, or Control for the control key,
  • A, Alt, M, or Meta for the alt key.

Most keys can be specified with a single character (such as numbers, Latin letters, etc.). The rest have aliases:

  • Left, Up, Right, Down for arrow keys,
  • Enter, Return, CR for the enter key,
  • BS, Backspace for the backspace key,
  • Home, End, PageUp, PageDown for common cursor position manipulation keys,
  • Tab for the tab key,
  • Del, Delete for the delete key,
  • Esc for the escape key,
  • Space for the space key,
  • Bar for the | key,
  • Minus for the - key,
  • Insert for the insert key,
  • Nul for the character with code 0,
  • F1, F2, ... for functional keys.

Modifiers and keys and separated by dashes (-), for example, C-c for Control+C, A-S-W for Alt+Shift+W. Please note that keys are case-sensitive: if you include the Shift modifier, then the key should be uppercase if applicable (S-A is correct while S-a won't work).

CONDITIONAL COMMANDS

  • chain [...]: Executes multiple commands in a sequence. The execution stops after the first command whose execution fails, the chain command automatically fails afterward.

  • if <command 1> [--else <command 2>] Evaluates the and execute one of two commands: <command 1> if the condition is true and <command 2> otherwise. If the --else attribute is not specified, and the evaluates to false, then the if command has no effect.

The conditions used as arguments for the if command can check the Hedgehog UI's state. Currently you can check the currently focused pane and the type of a selected item:

  • focused (feeds|episodes|search|log): Evaluates to true if the currently focused pane matches the specified argument. The selected pane can be either the list of feeds (feeds), the list of episodes in the currently selected list (episodes), the search results or the search progress screen (search), or the list of errors (log).

  • selected (nothing|special-feed|feed|group|episode|log-entry|search-result) Evaluates to true if an item in the selected pane is a special feed: all episodes or new episodes, a regular feed, a group, an episode, a log entry, or a search result. nothing case is applicable in situations when the list in the currently selected pane is empty.

You can combine multiple conditions using both or either command such that both <condition> [<condition> ...] evaluates to true if and only if all conditions evaluate to true. Similarly, either <condition> [<condition> ...] evaluates to true if at least one of the conditions is true.

CONFIGURATION

Hedgehog is configured by executing the commands described in the [COMMANDS][] section of this manual. The effect of these commands lasts until Hedgehog restarts. In order for the configuration to be persistent across restarts, they should be inserted in the rc file in the config directory.

Hedgehog considers multiple directories when loading its configuration: command lists and themes, in a way that is similar to how PATH environment variable is used by the operating system. The configuration path can be configured via --data-path CLI argument for Hedgehog executable or HEDGEHOG_DATA environment variables. Both these options append the set of directories to the default paths. The default paths are:

  • /usr/share/hedgehog and ./usr/share/hedgehog (only on UNIX-based OSes);
  • the parent directory of the Hedgehog's executable (only on Windows); * user's config directory: ~/.config/hedgehog on UNIX-based OSes and \Users\<user>\AppData\Roaming on Windows.

When looking for a file to load (using exec or theme load command) Hedgehog searches for the existing file by iterating through data directories from the last one to the first one, meaning the directory specified by the user has the highest priority, and global configuration has the lowest.

An exception to this rule is loading the startup commands. There is a special file named rc in the data directory. Hedgehog will execute commands in such files in all data directories in the opposite order: starting with the system-wide configuration followed by user-defined configuration files.

Each configuration file (both rc file and themes) contains a series of commands, each located on a separate line. The interpreter ignores empty lines and comments (sections starting with #).

CONFIGURATION OPTIONS

This section list options that can be set using the set command.

  • date-format: The format of the publication date following the syntax of strftime(3) function.

  • label-playback-status-playing: The label displaying in the player status bar in the playing state.

  • label-playback-status-paused: The label displaying in the player status bar in the paused state.

  • label-playback-status-bufffering: The label displaying in the player status bar when the audio stream is buffering.

  • label-playback-status-none: The label displaying in the player status bar when no episode is playing.

  • label-playback-status-none: The label displaying in the player status bar when no episode is playing.

  • label-episode-new: The label displaying in the library when the episode is new.

  • label-episode-seen: Label displaying in the library when the episode is not new but hasn't been played. An episode can reach this status using mark command.

  • label-episode-playing: The label displaying in the library when the episode is currently being played.

  • label-episode-started: The label displaying in the library when the episode was started but not completed and is not currently playing.

  • label-episode-finished: The label displaying in the library when the episode was completed.

  • label-episode-finished: The label displaying in the library when the previous playback attempt has failed with an error.

  • label-feed-error: The label displaying in the library list for feeds that could not be updated due to an error.

  • feed-updating-chars: The set of characters used for the episode loading indicator. The characters will be displayed one-by-one looped.

  • animation-tick-duration: The duration of the animation frame for the loading indicator expressed in milliseconds.

  • update-on-start: The flag indicating whether enabled feeds should be updated on startup.

  • show-episode-number: The flag indicating whether episode and season number should be displayed for episodes in the library.

  • hidden: The flag indicating whether the episodes that are hidden using the hide command should be visible in the library.

  • progress-bar-width: The number of characters allocated to the progress indicator in the player state bar.

  • progress-bar-chars: The string, characters of which are used for the progress indicator.

THEMING

Hedgehog allows extensive customization of colors and text styles for any component of its user interface. As with any other customization option, changing the visual style of the program is performed via issuing commands. Hedgehog supports a separate category of theming commands. They can be issued us subcommands of theme or loaded from a separate file via theme load (the theme prefix isn't used for commands in the theme file).

THEMING COMMANDS

  • reset: Clears all styles. After this command is executed, all styling assigned to any component in any state will be cleared.

  • load [--extend]: Reads a file and executes all theming commands from it. Note that can be either an absolute or relative path. In case of a relative path, Hedgehog applies the same logic as for searching the configuration files but with a small difference. The theme file may have a .theme extension.

    Hedgehog will try to locate a file both with and without it, all existing styling is cleared before a theme file is loaded. Inclusion of --extend flag prevents this.

  • set : Applies the styling to a component identified by the . The syntax of each argument is specified further.

STYLE SYNTAX

Styles are specified using a special syntax where multiple modifiers separated by single or multiple whitespace characters.

  • fg:, bg:: Sets the foreground or background color of a component, respectively. The color itself can be specified using any of three ways: a 24-bit RGB color in hexadecimal form preceded by a percentage sign (%FFFFFF for white), an 8-bit xterm color preceded by a dollar sign ($231 for White/Grey100) or using a color's name (either black, blue, cyan, darkgray, gray, green, lightblue, lightcyan, lightgreen, lightmagenta, lightred, lightyellow, magenta, red, white, or yellow). There is a special color identified by the keyword *reset` which corresponds to the terminal's default background or foreground color. Please note that not all color modes may be supported by your terminal emulator. Named colors may also be overridden by the terminal's configuration.

  • +, -: : Adds or removes a modifier. A modifier is a special attribute of a terminal cell that changes some of its visual characteristics. Removing a modifier is useful when you want to override the existing styling of a component with modifiers already applied. Note, that different terminal emulators may interpret some modifiers differently or not support them at all.

The modifiers list include:

  • bold increases the text intensity,
  • crossedout crosses the text,
  • dim decreases the text intensity,
  • hidden hides the text,
  • italic emphasizes the text,
  • rapidblink makes the text blinking (≥ 150 times per minute),
  • reversed swaps background and foreground color,
  • slowblink makes the text blinking (≤ 150 times per minute),
  • underlined underlines the text.

SELECTOR SYNTAX

A selector is a string that identifies a UI element in a specific state. Selectors follow any of the following forms:

  • statusbar.empty: The status bar (the bottom row of the screen) when it doesn't display any content.

  • statusbar.command[.prompt]: The status bar when it's used for command entry. .prompt is used for the command's prompt (colon at the beginning) only.

  • statusbar.confirmation: The status bar when it's used for prompting the user to confirm some action.

  • statusbar.status[:error|:warning|:information][.label]: The status bar when it's used for displaying the status message. The status can be of different severities (error, warning or information). The label is a short string placed before some messages (mostly errors).

  • list.divider: The divider between two columns or rows in the library.

  • list.item()*[]: where
    =:focused|​:selected|​:playing|​:hidden|​:missing-title|​:feed|​:feed-updating|​:feed-error|​:feed-special|​:episode|​:episode-error|​:episode-new|​:episode-started|​:episode-finished|​:search|​:log-entry
    =.state|​.title|​.feed-title|​.episode-number|​.duration|​.date|​.loading|​.author|​.genre|​.episodes-count|​.new-count|​.details

    The list item or its component. The list item can be in multiple states: It can belong to a list that is focused (:focused), it can be selected (:selected), it can describe an episode that is currently being played (:playing), an episode that was hidden from the feed but is visible due to value of hidden option, an episode or feed for which there is no title (for example, it wasn't specified by the podcast's creator, or it wasn't loaded yet, :missing-title).

    The rest of the state options define an entry in a specific list and in a context-specific state. Options starting with :feed describe list entries in the list of feeds the user is subscribed to. More specific states allow restricting styling for certain situations only: feeds that are in the process of being updated (:feed-updating), if the previous attempt to update it failed (:feed-error), and if the feed is special: either the list of all episodes from all subscriptions or all new episodes (:feed-special).

    Episode list entries (:episodes) can be selected by their state also: episodes can be either new, meaning never played (:episode-new), started meaning that playback was started but stopped before the entirety of the episode was listened to (:episode-started), finished when the episode was listened to until the end (:episode-finished), or playback failed due to an error (:episode-error).

    The search results entries and message log entries can be specified via :search and :log-entry respectingly.

    Styling can be applied to the whole row or a specific part of it. For a later case, you may extend this selector with the name of such part. Some of these are used by many lists. These include the name of the feed or episode (.name), a state indicator usually displayed on the right (.state), and an ellipsis that are displayed when the data is being loaded from the database for more time than usual. Most though are list specific. The episodes list includes an episode and season number (.episode-number), the name of a feed where this episode is located (.feed-title), the duration of the episode (.duration), the date when it was published (.date). Search result entries include the name of the autor who publishes the podcast (.author), its genre (.genre), the number of episodes in the feed (.episodes-count). The list of feeds along with the title includes a number of new episodes (.new-count). The log entry details are selected as .details.

    This selector is also used for empty parts of the list.

  • empty[:focused][.title|.subtitle]: The list with no entries. It usually contains a title (.title) and a text describing why the list is empty and what can be done to change that (.subtitle). As is a regular list, the empty list can be in the focused state (:focused). It's recommended that styling for lists and empty lists match in regard to the focused state.

  • player[][]: where
    =:buffering|:paused|:playing|:stopped
    =.episode|.feed|.progress|.status|.timing

    The playback status bar on the second from the bottom line of the screen. It consists of some parts which are (from left to right): status indicating the current playback status (buffering, paused, etc., .status), the name of the episode (.episode), the name of a feed containing the currently playing episode (.feed), the progress bar (.progress), and the current position within the stream along with its total duration (.timing).

    The remaining options allow you to specify different styles depending on the current state of the playback.

Above, [...] denotes an optional part, ...|... denotes that either of two or more options can be used, (...)* denotes the part that can repeat or not be present.

Selectors can be specific, describing a single UI element in a specific state or be general, specifying many elements or not specifying a state. When the style is applied using a selector, it is applied to all components that can be described by it in the order the styling is set. For example styles for player.status will override player:playing.status, so more specific styles should be specified later than more general ones.

KEY MAPPING

This section describes the default key mapping of Hedgehog. Note that any key mapping can be changed by custom configuration via man and unmap commands.

  • Up, k moves the selection one row up,
  • Down, j moves the selection one row down,
  • Home moves to the first row in the list,
  • End moves to the last row in the list,
  • PageUp moves to the item one screen up,
  • PageDown moves to the item one screen down,
  • Tab toggles between feeds and episodes lists,
  • Enter either focuses on the episodes list, starts playing the episode, or subscribes to the search result depending on the context,
  • Esc returns to the library from either the error log or search results,
  • C-c, q quits Hedgehog (includes confirmation),
  • Delete deletes the currently selected feed (includes confirmation),
  • o opens either podcast's or episode's Web URL,
  • f stops playback and marks the episode as finished,
  • Right moves forward by 5 seconds,
  • Left moves backwards by 5 seconds,
  • c toggles between paused and playing states,
  • m toggles between muted and unmuted states,
  • Minus decreases volume by 10%,
  • =, +, S-+ increases volume by 10%,
  • . repeats the last command,
  • : begins command entry (cannot be remapped).

COMMAND ENTRY KEY MAPPING

The following are key combinations available in the command entry mode. These cannot be remapped.

  • C-c, Esc stops entry, discards the input,
  • Backspace, C-h removes character before the cursor,
  • Delete removes character after the cursor,
  • Up, Down navigates through commands history,
  • Enter stops entry, accepts and executes the command,
  • Tab performs completion,
  • Left moves the cursor one character to the left,
  • Right moves the cursor one character to the right,
  • C-Left moves the cursor one word to the left,
  • C-Right moves the cursor one word to the right,
  • Home moves the cursor to the first character,
  • End moves the cursor to the last character,
  • Backspace, C-h removes character before the cursor,
  • Delete removes character after the cursor,
  • S-Backspace removes all characters before the cursor,
  • S-Delete removes all characters after the cursor,
  • A-Backspace, C-w removes a word after the cursor,
  • C-Delete removes a word before the cursor.

BUGS

If you find a bug, you have a recommendation or suggestions for Hedgehog, please file an issue at https://github.com/poletaevvlad/Hedgehog/issues. If you wish to contribute to Hedgehog, you are welcome to participate in the development at https://github.com/poletaevvlad/Hedgehog