Extension
index
/home/laszlo/Dev/joko-gtk-builder/Jokosher/Extension.py

#       THIS FILE IS PART OF THE JOKOSHER PROJECT AND LICENSED UNDER THE GPL. SEE
#       THE 'COPYING' FILE FOR DETAILS
#
#       Jokosher Extension API.
#
#-------------------------------------------------------------------------------

 
Modules
       
ConfigParser
Globals
gettext
gobject
gst
gtk
imp
inspect
os
pickle
pkg_resources
traceback

 
Classes
       
ExtensionAPI

 
class ExtensionAPI
    Defines the API for implementing external extensions for Jokosher.
 
  Methods defined here:
__init__(self, mainapp)
Creates a new instance of ExtensionAPI.
 
Parameters:
        mainapp -- reference the MainApp Jokosher window.
add_end_of_stream_handler(*args, **kwargs)
Adds a function to receive and end-of-stream notification.
 
Parameters:
        function --     the function that will receive the notification
        
Returns:
        0 = end of stream handler successfully added
        1 = no project currently open
add_export_format(*args, **kwargs)
Adds a new format that the user can select from the filetype drop down box
in the 'Mixdown Project' dialog.
 
Parameters:
        description -- string for the drop down box. i.e: 'Ogg Vorbis (.ogg)'.
        extension -- string of the file extension without a '.'. i.e: 'ogg'.
        encodeBin -- string used by gst.parse_bin_from_description to create
                                a bin that can encode and mux the audio when added to a
                                pipeline. i.e: 'vorbisenc ! oggmux'.
        checkIfValid -- If True, Jokosher will check if the encodeBin string is valid before adding
                                it to the export dialog. If you know a string to be correct, this parameter
                                should be False because checking will make startup take longer.
Returns:
        0 = the new export format was successfully added to Jokosher.
        1 = invalid options.
        2 = a format with the same three values already exists.
        3 = cannot parse or create encoder/muxer bin.
add_file_to_instrument(*args, **kwargs)
Creates a new Event from a given file and adds it to the Instrument 
with the correspondent id, at the given position.
 
Parameters:
        instr_id -- unique id of the Instrument.
        uri -- file with the Event to load.
        position -- position in seconds to insert the new Event at.
 
Returns:
        0 = the Event was loaded successfully.
        1 = bad URI or file could not be loaded.
        2 = the Instrument with id 'instr_id' was not found.
add_file_to_selected_instrument(*args, **kwargs)
Creates a new Event from a given file and adds it to the first
selected Instrument, at the given position.
 
Parameters:
        uri -- file with the Event to load.
        position -- position in seconds to insert the new Event at.
 
Returns:
        0 = the Event was loaded successfully.
        1 = bad URI or file could not be loaded.
        2 = no Instrument selected.
add_instrument(*args, **kwargs)
Adds an Instrument to the current Project.
 
Parameters:
        instr_type -- type of the Instrument to be added.
        instr_name -- name of the Instrument to be added. This value can be
                                        obtained via get_available_instruments().
 
Returns:
        -1 = that Instrument type does not exist.
        >0 = if the Instrument is successfully added,
                the return value will be the ID of that Instrument.
add_instrument_effect(*args, **kwargs)
Adds an effect to an Instrument.
 
Parameters:
        instr_id -- ID of the Instrument to add the effect to.
        effect_name -- name of the effect to be added to Instrument.
        
Returns:
        0 = the effect was successfully added to the Instrument.
        1 = the Instrument with id 'instr_id' was not found.
        2 = the LADSPA plugin named 'effect_name' was not found.
add_menu_item(*args, **kwargs)
Adds a menu item to a Jokosher extension menu.
 
Parameters:
        menu_item_name -- name of the new menu.
        callback_function -- function to be called when the menu is invoked.
                                                
Returns:
        reference to the new menu item.
create_new_instrument_type(*args, **kwargs)
Creates a new Instrument type in the user's JOKOSHER_DATA_HOME/instruments folder.
It will then be automatically loaded on startup.
 
Parameters:
        defaultName -- the en_GB name of the Instrument.
        typeString -- a unique type string to this particular Instrument file.
        imagePath -- absolute path to the Instrument's image (png).
 
Returns:
        0 = the new Instrument type was successfully created.
        1 = file already exists or defaultName is already used by a loaded Instrument.
        2 = cannot load image file.
        3 = cannot write to JOKOSHER_DATA_HOME/instruments or JOKOSHER_DATA_HOME/instruments/images.
delete_instrument(*args, **kwargs)
Removes an Instrument from the Project.
 
Parameters:
        instrumentID -- ID of the Instrument to be removed.
delete_instrument_type(*args, **kwargs)
Deletes an instrument type from the user's JOKOSHER_DATA_HOME/instruments 
directory (deleting default instruments isn't allowed)
 
Parameters:
        typeString -- The instrument type, the instrument name is translated
                                so we can't use that one
 
Returns:
        0 = Instrument successfully deleted
        1 = Instrument is a default instrument and cannot be deleted
        2 = Error deleting instrument files
        3 = Error removing instrument from cache
        4 = Cannot find an instrument with that type string
export_to_file(*args, **kwargs)
Exports the entire project to a single audio file at the URI given,
and encoded with the Gstreamer encoding bin given.
 
Parameters:
        uri -- string of the location to save the file.
        encodeBin -- gst-launch formatted string used to create the 
                        bin that will encode the audio before being written to disk.
get_bpm(*args, **kwargs)
Returns the current beats per minute for the Project.
get_button_states(*args, **kwargs)
Obtains the states of the transport toggle buttons
 
Returns:
        a dictionary containing a set of tuples representing the
        toggle state and sensitive state of the transport buttons
get_config_value(*args, **kwargs)
Obtains the config value saved under this key.
 
Parameters:
        key -- config key to obtain the value of.
        
Returns:
        the value of the config key, or None if the value doesn't exist.
get_data_file(*args, **kwargs)
Obtain the data file saved under this key.
 
Parameters:
        extName -- name of the extension loading the file.
        key -- config key to obtain the data file of.
        
Returns:
        the data retrieved, or None if the value doesn't exist
                or couldn't be loaded.
get_export_formats(*args, **kwargs)
Returns the list of dictionaries of available export formats
that Jokosher knowns about. Even if a format is not listed
here, you can still export with it by passing the gst-launch
formatted string to export_to_file.
An example format dictionary for Ogg: 
{"description":"Ogg Vorbis", "extension":"ogg", "pipeline":"vorbisenc ! oggmux"}
get_instrument_effects(*args, **kwargs)
Obtains the current effects applied to an Instrument.
 
Parameters:
        instr_id -- ID of the Instrument to obtain the effects from.
 
Returns:
        list = list of effects applied to the Instrument.
        1 = the Instrument with id 'instr_id' was not found.
get_instrument_volume(*args, **kwargs)
Obtains the volume of an Instrument.
 
Parameters:
        instr_id -- ID of the Instrument to obtain the volume from.
        
Returns:
        volume = volume of the Instrument.
        1 = the Instrument with id 'instr_id' was not found.
get_meter(*args, **kwargs)
Returns the current meter of the project as a tuple.
get_pipeline_state(*args, **kwargs)
Obtains up the state of the pipeline
 
Returns:
        the state of the pipeline
get_position(*args, **kwargs)
Gives the current position in pipeline
 
Returns: time in seconds
get_position_as_bars_and_beats(*args, **kwargs)
Gives the current position in pipeline
 
Returns: position as a tuple (bars, beats, ticks)
get_position_as_hours_minutes_seconds(*args, **kwargs)
Obtains the current playback position in hours, minutes, seconds.
 
Returns:
        tuple of the current position as (hours, minutes, seconds, milliseconds).
        None - no project is currently open
hide_main_window(*args, **kwargs)
Makes the main Jokosher window invisible.
 
Parameters:
        timeout -- Number of milliseconds to wait before reshowing the window (0 for infinity).
list_available_effects(*args, **kwargs)
Obtain the available LADSPA effects.
 
Returns:
        a list with all available LADSPA effects.
list_available_instrument_types(*args, **kwargs)
Obtain a list of tuples in the format:
        (instr_name, instr_type, instr_pixbuf)
for each of the *.instr files that have been cached.
 
Considerations:
        These Instruments are *not* the ones in the current Project,
        but those available for any Jokosher Project.
        
Returns:
        a list with tuples describing each available Instrument in Jokosher.
list_project_instruments(*args, **kwargs)
Obtain a list of tuples in the format:
        (instr_id_number, instr_name, instr_type, instr_pixbuf)
for each of the Instruments currently shown in the Project.
 
Returns:
        a list with tuples describing each Instrument in the Project.
play(*args, **kwargs)
Manipulates the Project's playback status in Jokosher.
 
Parameters:
        play_state --   True = play the Project from the beginning.
                                        False = stop all playback.
quit(*args, **kwargs)
Quits Jokosher.
record(*args, **kwargs)
Starts the project recording
remove_end_of_stream_handler(*args, **kwargs)
Removes a function from the end-of-stream-handler list
 
Parameters:
        function -- the function to remove
 
Returns:
        0 = end of stream handler successfully removed
        1 = no project currently open
remove_export_format(*args, **kwargs)
Removes an export format that was previously added using add_export_format.
 
Parameters:
        description -- string for the drop down box. i.e: 'Ogg Vorbis (.ogg)'.
        extension -- string of the file extension without a '.'. i.e: 'ogg'.
        encodeBin -- string used by gst.parse_bin_from_description to create
                                a bin that can encode and mux the audio when added to a
                                pipeline. i.e: 'vorbisenc ! oggmux'.
Returns:
        0 = successfully removed the export format.
        1 = no export format exists with those parameters.
remove_instrument_effect(*args, **kwargs)
Removes an effect from an Instrument.
 
Parameters:
        instr_id -- ID of the Instrument to remove the effect from.
        effect_num -- index of the effect inside the Instrument's effects array.
 
Returns:
        0 = the effect was successfully removed.
        1 = effect_num out of range.
        2 = the Instrument with id 'instr_id' was not found.
        3 = unknown GStreamer error.
seek(*args, **kwargs)
Performs a seek on the pipeline
 
Parameters:
        start_position -- position to seek to
        end_position -- position where playing will stop
set_bpm(*args, **kwargs)
Sets the current beats per minute for the Project.
 
Parameters:
        bpm -- the beats per minute to set.
set_config_value(*args, **kwargs)
Sets a new config value under a given key for later retrieval.
 
Parameters:
        key -- name of the key to save the value under.
        value -- value to save.
set_data_file(*args, **kwargs)
Stores a new data file under a given key for later retrieval.
It must a serializable object.
 
Parameters:
        extName -- name of the extension loading the file.
        key -- name of the key to save this data under.
        data -- data to store.
set_instrument_volume(*args, **kwargs)
Sets the volume of an Instrument.
 
Parameters:
        instr_id -- ID of the Instrument to change the value to.
        instr_volume -- value the volume of the Instrument should be set to.
        
Returns:
        0 = the volume was successfully changed.
        1 = the Instrument with id 'instr_id' was not found.
set_meter(*args, **kwargs)
Changes the current time signature.
 
Example:
        nom = 3
        denom = 4
        
        would result in the following signature:
                3/4
 
Parameters:
        nom -- new time signature nominator.
        denom --new time signature denominator.
set_window_icon(*args, **kwargs)
Sets the specified window to use the Jokosher icon.
 
Parameters:
        window -- the window which will use the Jokosher icon as its icon in the window border.
set_window_parent(*args, **kwargs)
Sets the main Jokosher window as the parent for the given window.
 
Parameters:
        window -- window who's parent is to be set as the main window.
show_main_window(*args, **kwargs)
Makes the main Jokosher window visible.
 
Returns:
        False -- stop calling the callback on a timeout_add.
stop(*args, **kwargs)
Stops the project if it's currently playing.
Same as play(play_state=False).
toggle_mute_instrument(*args, **kwargs)
Mutes an Instrument.
 
Parameters:
        instr_id -- ID of the Instrument to mute.
        
Returns:
        0 = the Instrument was successfully muted.
        1 = the Instrument with id 'instr_id' was not found.

 
Functions
       
exported_function(f)
Wraps any exported functions so that exceptions do not cross the exported API.
Any exceptions caught by this function, should be a return error code from 
exported function.
 
Parameters:
        f -- function to wrap.
        
Returns:
        the wrapped function.

 
Data
        API = None
EXTENSION_DIR_USER = '/home/laszlo/.local/share/jokosher/extensions/'
PREFERRED_EXTENSION_DIR = '/home/laszlo/Dev/joko-gtk-builder/Jokosher/../extensions'
RESP_INSTALL = 9999
RESP_REPLACE = 9998