Package: cosmodoit
COSMOS Analysis ToolboxToolbox for analysing music performance.There are 2 main ways to use this toolbox:As a one-stop pipeline which computes all features, recomputing only what has changedAs an importable package, accessible from any python codeSetting upEnsurePython 3andMusescoreare installed.Install the package through pip :pip install cosmodoit(orpip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ cosmodoituntil the package is on the main PyPI server). Depending on the python installation, replacingpipbypip3,python -m piporpython3 -m pipmight be required.Running the analysis pipelineTL;DR: Justcosmodoit!The pipeline should figure out what to do.By default, the pipeline will look for pieces under the current folder, each in its own subfolder; use the--dir <target_dir>option to override that behavior (e.g.,cosmodoit --dir example_data, whereexample_datacontains piece subfolders).
Each piece should be in its own folder, and requires :a performance in.midformat;a score in.msczformat (Musescore);a recording in.wavformat.[Optional] a manual beats annotation, ending in_beats_manual.csv(will override the automatic beats extraction if present)If one or more filetypes are missing, some features will not be computed, but those which can be derived from the existing data will still be computed. The files are not required to share the same base name, but it is recommended for tidyness. In case more than one file matches a type, a warning will be issued and an arbitrary one will be used for the computations.Computed files will be outputted to the corresponding directory. An option to specify a target directory might be available in the future.It is possible to run only a given feature and/or a given piece by usingcosmodoit <feature>[:<piece>](intermediate features will still get computed if needed). Either can accept wildcards*, e.g.cosmodoit loudnessorcosmodoit loudness:*to compute loudness for all detected pieces orcosmodoit *:Mazurka\ 17-4to compute all features on Mazurka 17-4.Typecosmodoit listto list all valid feature tasks, orcosmodoit list --allto list all subtasks — one per feature/piece pair.To force a task to be recomputed, typecosmodoit forget <task>and it will be run on the next execution (--allto forget all tasks).Runningcosmodoit cleanwill remove the intermediary files, keeping only the final features.If processing is long, usingcosmodoit -n <N> -P threadwill run tasks on N threads.Some tasks can be configured, for example to set the window length for loudness. Parameters can be listed usingcosmodoit help <task>, and are set through apyproject.tomlconfiguraion file (seemusic_features/templates/pyproject.tomlfor a sample of the format). Changes to the parameters will be picked up by thedoitsystem and corresponding features (including dependent features) will be recomputed on the next run.
At the moment, parameters can only be supplied at the collection level: to apply parameters to a single piece, it must be put in a separate collection.Toolbox API conventionEach feature is handled by a different submodule, namedget_<feature>. Submodules which do not abide by that convention are meant for internal use only.Each submodule contains at least 3 functions for external use:aget_<feature>function which handles the computation of the feature. The exact signature differs for each (see individual documentation).awrite_<feature>and aread_<feature>function to handle input and output.To use them just import them into your code:from cosmodoit.get_<feature> import get_<feature> write_<feature>(or any other valid import statement)Extending the toolboxThe toolbox is meant to be easily extendable. To add a new feature, add a new submodule namedget_<feature>. To be picked up by the pipeline, it must be added to thesubmodulesvariable indodo.pyand include in the module's namespace:[required] agen_tasks(piece_id, targets, **kwargs)function to generatedoittasks (see thedocumentation). See existing functions for the usage of the parameters;[recommended] atask_docsdictionary, which maps the (sub)tasks' names to description strings;[optional] aparam_sourcesiterable, which lists the functions that provide keyword-only parameters that should be exposed through the config file.If a new input type is required, it can be added as anInputDescriptorin thediscover_files_by_piecefunction of thedodo.pymodule, which describes the patterns (positive and negative) to match when scanning for the file.It is recommended, but not strictly required, to provide the functions of the API convention if you add a new feature.