This module contains a collection of reusable Urwid widgets and helper functions for processing user input and generating helper output in a consistent way.
Given a audiotools.Messenger object, displays all the available file formats one can select with a utility’s -t argument in a user-friendly way.
Given a audiotools.Messenger object and an audiotools.AudioFile subclass, displays all the available output qualities for that audio type one can select with a utility’s -q argument.
Given metadata_choices[choice][track] where each choice contains a list of audiotools.MetaData objects and all choices must have the same number of objects, along with a audiotools.Messenger object, queries the user for which metadata choice to use and returns that list of audiotools.MetaData objects.
If use_default is True, this simply returns the metadata for the first choice.
This function is for processing the input and output options for utilities such as track2track and cd2track.
metadata_choices[choice][track] is a list of audiotools.MetaData objects and all choices must have the same number of objects.
input_filenames is a list of audiotools.Filename objects where the number of filenames must match the number of audiotools.MetaData objects for each choice in metadata_choices.
output_directory is a string to the output directory, indicated by a utility’s -d option.
format_string is a UTF-8 encoded plain string of the output file format, indicated by a utility’s --format option.
output_class is an audiotools.AudioFile class, indicated by a utility’s -t option.
quality is a string if the output quality to use, indicated by a utility’s -q option.
messenger is an audiotools.Messenger object used for displaying output.
use_default, if indicated, is applied to this function’s call to select_metadata() if necessary.
Yields a (output_class, output_filename, output_quality, output_metadata) tuple for each output file where output_class is an audiotools.AudioFile object, output_filename is a audiotools.Filename object, output_quality is a compression string, and output_metadata is a audiotools.MetaData object.
Raises audiotools.UnsupportedTracknameField or audiotools.InvalidFilenameFormat if the format_string option is invalid.
Raises audiotools.DuplicateOutputFile if the same output filename is generated more than once.
Raises audiotools.OutputFileIsInput if one of the output files is the same as any of the input files.
Given a audiotools.Messenger object, displays a message about Urwid being unavailable and offers a suggestion on how to obtain it.
Given a list of argument strings (such as from sys.argv) returns a Unicode string indicating how one might call the given program using xargs.
This is a base class for implementing the user interface for TTY-based audio players.
player is a audiotools.player.Player-compatible object.
Stop playing the current track and begin playing the next one. This must be implemented in a subclass.
Stop playing the current track and begin playing the previous one. This must be implemented in a subclass.
Typically called by PlayerTTY.next_track() and PlayerTTY.previous_track(), this sets the current metadata to the given values for displaying to the user.
Calls audiotools.player.Player.toggle_play_pause() on the internal audiotools.player.Player object to suspend or resume output.
Calls audiotools.player.Player.stop() on the internal audiotools.player.Player object to stop playing the current file completely.
Returns the values from audiotools.player.Player.progress() which indicate the current status of the playing file.
Given the amount of PCM frames sent and total number of PCM frames as integers, returns a Unicode string of the current progress to be displayed to the user.
Given a audiotools.Messenger object and sys.stdin file object, this runs the player’s output loop until the user indicates it should exit or the input is exhausted.
Returns 0 on a successful exit, 1 if it exits with an error.
True if Urwid is available and is of a sufficiently high version. False if not.
If Urwid is available, the following classes will be in this module for use by utilities to generate interactive modes. If not, the classes will not be defined.
This is an Urwid Frame subclass for populating track data and options for multiple output file utilities such as track2track and cd2track.
track_labels is a list of Unicode strings, one per track
metadata_choices[choice][track] is a list of audiotools.MetaData objects per choice, one per track
input_filenames is a list of audiotools.Filename objects, one per track.
output_directory is a string to the output directory, indicated by a utility’s -d option.
format_string is a UTF-8 encoded plain string of the output file format, indicated by a utility’s --format option.
output_class is an audiotools.AudioFile class, indicated by a utility’s -t option.
quality is a string if the output quality to use, indicated by a utility’s -q option.
completion_label is an optional Unicode string to display in the widget’s “apply” button used to complete the operation.
This widget is typically executed as follows:
>>> widget = audiotools.ui.OutputFiller(...) # populate widget with metadata and command-line options
>>> loop = urwid.MainLoop(widget,
... audiotools.ui.style(),
... unhandled_input=widget.handle_text,
... pop_ups=True)
>>> loop.run()
>>> if (not widget.cancelled()):
... # do work here
... else:
... # exit
Yields a (output_class, output_filename, output_quality, output_metadata) tuple for each output file where output_class is an audiotools.AudioFile object, output_filename is a audiotools.Filename object, output_quality is a compression string, and output_metadata is a audiotools.MetaData object.
Note
This method returns freshly-created audiotools.MetaData objects, whereas process_output_options() resuses the same objects passed to it.
Because OutputFiller may modify input metadata, we don’t want to risk modifying objects used elsewhere.
Returns the currently selected output directory as a plain string.
Returns the current format string as a plain, UTF-8 encoded string.
Returns the current audiotools.AudioFile-compatible output class.
Returns the current output quality as a plain string.
This is an Urwid Frame subclass for populating track data and options for a single output track utilities such as trackcat.
track_label is a Unicode string.
metadata_choices[choice] is a list of audiotools.MetaData objects for all possible choices for the given track.
input_filenames is a list or set of audiotools.Filename objects for all input files, which may include cuesheets or other auxiliary data.
output_file is a plain string of the default output filename.
output_class is an audiotools.AudioFile class, indicated by a utility’s -t option.
quality is a string if the output quality to use, indicated by a utility’s -q option.
completion_label is an optional Unicode string to display in the widget’s “apply” button used to complete the operation.
This widget is typically executed as follows:
>>> widget = audiotools.ui.SingleOutputFiller(...) # populate widget with metadata and command-line options
>>> loop = urwid.MainLoop(widget,
... audiotools.ui.style(),
... unhandled_input=widget.handle_text,
... pop_ups=True)
>>> loop.run()
>>> if (not widget.cancelled()):
... # do work here
... else:
... # exit
Returns (output_class, output_filename, output_quality, output_metadata) tuple to apply to the single output track. output_class is an audiotools.AudioFile object, output_filename is a audiotools.Filename object, output_quality is a compression string, and output_metadata is a audiotools.MetaData object.
This is an Urwid Pile subclass for selecting and editing a single set of metadata from multiple choices. It is used by OutputFiller and SingleOutputFiller as necessary to allow the user to edit metadata when setting options.
track_labels is a list of Unicode strings, one per track.
metadata_choices[choice][track] is a list of audiotools.MetaData objects per choice, one per track
status is an urwid.Text object to display status text such as key shortcuts.
Selects the previous item in the current set of metadata, such as the previous track or the previous field, depending on how the data is swiveled.
Selects the next item in the current set of metadata, such as the next track or the next field, depending on how the data is swiveled.
Yields a new, populated audiotools.MetaData object per track, depending on the current selection and its values.
This is an Urwid Frame subclass for editing a single set of metadata across multiple tracks.
tracks is a list of (id, label, metadata) tuples in the order they are to be displayed with id is some unique, hashable ID value, label is a Unicode string, and metadata is an audiotools.MetaData object, or None.
on_text_change(widget, new_value) is a callback for when any text field is modified.
on_swivel_change(widget, selected, swivel) is a callback for when tracks and fields are swapped.
Selects the previous item in the current set of metadata, such as the previous track or the previous field, depending on how the data is swiveled.
Selects the next item in the current set of metadata, such as the next track or the next field, depending on how the data is swiveled.
Yields a (track_id, metadata) tuple per edited track where track_id is the unique, hashable value entered at init-time, and metadata is a newly created audiotools.MetaData object.
This is an Urwid LineBox subclass which places its title at the bottom instead of the top.
This is an Urwid PopUpLauncher subclass designed to work as an HTML-style <SELECT> dropdown.
items is a list of (label, value) tuples where label is a Unicode string and value is any object with an __eq__ method.
selected_value indicates which object in items is currently selected.
on_change(new_value, [user_data]) is a callback which is called whenever the selected item is changed where new_value is the value from the item tuple.
user_data is an object passed to the on_change callback.
label is a Unicode label string for the selection box.
Given a Unicode label and value object, sets the selection to the given values.
Returns the selected value object.
Replaces all the items in the dropdown with new values. items is a list of (label, value) tuples where label is a Unicode string and value is any object with an __eq__ method.
selected_value indicates which object in items is currently selected.
This is an Urwid Columns subclass consisting of an editable output directory box and a directory tree browser button.
initial_directory is a plain string of the starting directory.
on_change(widget, new_directory, user_data) is a callback which is called whenever the directory is changed.
user_data is passed to the on_change callback.
Returns the currently selected directory as a plain string.
This is an Urwid Edit subclass for editing a single output filename.
initial_filename is a plain string of the starting filename.
Returns the edited filename as a plain string.
Updates the field’s value to the given filename, which is a plain string.
This is an Urwid Pile subclass for populating output options, including an output file previewer so one can see the results of changing the directory and format string in real-time.
output_directory is a string to the output directory, indicated by a utility’s -d option.
format_string is a UTF-8 encoded plain string of the output file format, indicated by a utility’s --format option.
output_class is an audiotools.AudioFile class, indicated by a utility’s -t option.
quality is a string if the output quality to use, indicated by a utility’s -q option.
input_filenames is a list of audiotools.Filename objects, one per input track.
metadatas is a list of audiotools.Metadata objects, oner per input track.
extra_widgets is a list of additional Urwid widgets to append to the pile.
metadatas is a list of audiotools.MetaData objects (which may be None), one per input track.
Returns (output_class, output_quality, [output filenames]) tuple where output_class is an audiotools.AudioFile, output_quality is a plain string and output_filenames is a list of audiotools.Filename objects, one per input filename.
This is an Urwid ListBox subclass for populating the options of a single output audio file.
output_filename is a plain string of the default output filename.
audio_class is an audiotools.AudioFile object.
quality is a plain string of the default output quality.
Returns (output_class, output_quality, output filename) where output_class is an audiotools.AudioFile, output_quality is a plain string and output_filename is a audiotools.Filename object.
This is an Urwid Frame subclass for implementing an interactive audio player. It cannot be instantiated directly; a subclass must implement its select_track method to determine what to play next.
player is a audiotools.player.Player-compatible object.
tracks is a list of (track_name, seconds_length, user_data) tuples where track_name is a Unicode string, seconds_length is the length of the track in seconds and user_data is some Python object.
total_length is the length of all tracks in seconds.
This widget is typically used as follows:
>>> player = PlayerGUISubclass(...) # instantiate PlayerGUI subclass widget with input
>>> loop = urwid.MainLoop(widget, # setup MainLoop to execute widget
... audiotools.ui.style(),
... unhandled_input=player.handle_text)
>>> loop.set_alarm_at(tm=time.time() + 1, # set timer to update player's progress bar
... callback=audiotools.ui.timer,
... user_data=player)
>>> loop.run()
Begins playing the selected audio track. This must be implemented by a subclass.
Updates the status of the given PlayerGUI object at regular intervals so that its progress bar moves properly.
Returns a list of widget style tuples for use with Urwid’s MainLoop object in order to style all interactive modes consistently.