Extension
index
/home/david/Projects/Jokosher/trunk/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_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'.
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/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/instruments or ~/.jokosher/instruments/images.
delete_instrument(*args, **kwargs)
Removes an Instrument from the Project.
 
Parameters:
        instrumentID -- ID of the Instrument to be removed.
get_config_value(*args, **kwargs)
Obtain 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_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.
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.
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.
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_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.
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/david/.jokosher/extensions/'
PREFERRED_EXTENSION_DIR = '/home/david/Projects/Jokosher/trunk/Jokosher/../extensions'
RESP_INSTALL = 9999
RESP_REPLACE = 9998