mappersession

Session management tools in python for the libmapper signal mapping framework

Installation

Simply run pip install mappersession in your python environment of choice.

Usage

Usage from the command-line

usage:
mappersession --load PATH [PATH ...] [--interactive] [--wait] [--persist] [--clear]
mappersession --unload PATH [PATH ...]
mappersession --save PATH [--description DESCRIPTION]
mappersession --print_session_tags

options:
-h, --help                  Show the help message and exit
--load PATH [PATH ...]      Mapping session JSON file(s) to load
--unload PATH [PATH ...]    Mapper session JSON file(s) to unload
--save PATH                 Save mapping session as JSON file
--interactive               Create libmapper signals for managing file
                            loading and unloading.
--wait                      Set if session should wait for missing
                            devices and signals and connected them as
                            they appear during session load
--wait_seconds              Similar to `--wait` option but only waits
                            for N seconds
--persist                   Remain active during session load and
                            (re)create maps as they appear.
--clear                     Set if maps should be cleared after saving
                            and/or before load. Warning – this will
                            clear all maps regardless of session tag!
--print_session_tags        Print a list of active session tags
--description DESCRIPTION   Description of session, used when saving

Examples:

Load a session file and wait indefinitely for needed signals to appear:

python -m mappersession --load mysession.json --wait

Load a session file and wait 10 seconds for needed signals to appear:

python -m mappersession --load mysession.json --wait_seconds 10

Unload a session file:

python -m mappersession --unload mysession.json

Replace a running session with another

python -m mappersession --unload sesh1.json --load sesh2.json

Start an interactive session with libmapper control signals for loading/unloading each file:

python -m mappersession --load session1.json session2.json --interactive

Save the current session and provide a description:

python -m mappersession --save mysession.json --description "This session does something cool"

Usage as a Python module

Importing the module

import mappersession as session

Saving a mapping session file

session.save(filename="", description="", values=[],
             view_name="", views=[], graph=None)

• param filename: The name of the file to save
• optional param description: A short description of the current session
• optional param values: Array of {name, value} pairs for signals to set on session load
• optional param view_name: Name of the GUI that's adding metadata
• optional param views: GUI related object for recreating the session
• optional param graph: A previously-allocated libmapper Graph object to use. If not provided one will be allocated internally.
• return: The session JSON object

Loading a mapping session file

session.load(filename, interactive=False, wait=False, persist=False, background=False, device_map=None, graph=None)

Loads session files and optionally waits for signals. If the optional argument device_map is provided, mappersession will attempt to match the exact device and signal name, otherwise it will substitute a wildcard for the device name and map to all matching signals. In either case signals belonging to devices that have the property hidden=True will not be matched.

The filename will be included in the session property for loaded maps.

• param filename (String or List): The session file(s) to load
• optional param interactive (Boolean): Starts an interactive session for managing multiple session files. A libmapper control signal is created for corresponding to each file; setting the control signal value to a non-zero value loads the file, and setting it to zero unloads the file.
• optional param wait (Boolean): Wait for missing signals during session load and create maps once they appear, default False
• optional param persist (Boolean): Continue running after creating maps in session, and recreate them as matching signals (re)appear, default False
• optional param background (Boolean): True if waiting for signals should happen in a background thread, default False
• optional param device_map (Dict): A dictionary specifying correspondences between device names stored in a session file and names of devices active on the network.
• optional param graph: A previously-allocated libmapper Graph object to use. If not provided one will be allocated internally.
• return (Dict): visual session information relevant to GUIs

Unloading a mapping session file

session.unload(filename, graph=None)

Unloads session files by removing maps tagged with the filename using a property named session.

• param filename (String or List): The session file(s) to unload
• optional param graph: A previously-allocated libmapper Graph object to use. If not provided one will be allocated internally.
• return (None)

Loading JSON-formatted session data

session.load_json(session_json, name=None, wait=False, persist=False, background=False, device_map=None, graph=None)

Loads a session JSON Dict with options for staging and clearing. If the optional argument device_map is provided, mappersession will attempt to match the exact device and signal name, otherwise it will substitute a wildcard for the device name and map to all matching signals. In either case signals belonging to devices that have the property hidden=True will not be matched.

If the optional name argument is provided it will be included in the session property for loaded maps.

• param session_json (Dict): A session JSON Dict to load
• optional param name (String): A name for the session; any maps created by this session will be tagged with the name.
• optional param wait (Boolean or Float): Wait for missing signals during session load and create maps once they appear, default False. Can be set to wait indefinitly (True) or for N seconds.
• optional param persist (Boolean): Continue running after creating maps in session, and recreate them as matching signals (re)appear, default False
• optional param background (Boolean): True if waiting for signals should happen in a background thread, default False
• optional param device_map (Dict): A dictionary specifying correspondences between device names stored in a session file and names of devices active on the network.
• optional param graph: A previously-allocated libmapper graph object to use. If not provided one will be allocated internally.
• return (Dict): visual session information relevant to GUIs

Get a list of active session tags

session.tags(graph=None)

• optional param graph: A previously-allocated libmapper graph object to use. If not provided one will be allocated internally.
• return (List): a list of active session tags