Merge pull request #5 from groupmm/dev

First release of playplot

.gitattributes

@@ -0,0 +1,3 @@
+*.ipynb filter=nbstripout
+*.zpln filter=nbstripout
+*.ipynb diff=ipynb

.gitignore

@@ -0,0 +1,15 @@
+.idea/
+*.egg-info
+sphinx/build
+venv
+dist
+build
+tests/_trial_temp
+*.pck
+/examples/.ipynb_checkpoints/
+
+examples/example_data/*
+!examples/example_data/__init__.py
+!examples/example_data/bach_bwv245_no22_vokalensemble_ilmenau.wav
+!examples/example_data/bach_bwv245_no22_vokalensemble_ilmenau_annotations.csv
+

LICENCE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2022 Daniel Keitel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Makefile

@@ -0,0 +1,24 @@
+build:
+	@(cd sphinx && make github)
+	@python -m build --sdist
+	@python -m build --wheel
+	@twine check dist/*
+
+publish:
+	@make build
+	@twine upload dist/*
+
+test-publish:
+	@make build
+	@twine upload --repository testpypi dist/*
+
+dev-install:
+	@pip uninstall -y playplot
+	@pip install -e .
+
+install:
+	@make build
+	@pip uninstall -y playplot
+	@pip install --no-index --find-links dist/ playplot
+
+.PHONY: build publish

README.md

@@ -1 +1,100 @@
-# make-plot-playable
+# Playplot
+
+This repository contains a Python package called _playplot_, 
+which provides an __interactive audio playback for matplotlib plots including the creation, navigation, and synchronization of such plots.__
+Each plot is handled in its own process, allowing smooth animations without a blocking main thread/process.
+Plots can be started from a Python __script__ or an __interactive notebook__, with plots being shown in separate windows on the machine
+where the kernel is running.
+
+
+## References
+
+Daniel Keitel, Meinard Müller, Christof Weiß, and Sebastian Rosenzweig.  
+_Playplot: A Python Package to Sync Matplotlib Plots to Audio._  
+To be submitted to the Journal of Open Source Software (JOSS).
+
+## Installing
+
+To use the library just install it via pip.
+```pip install playplot```
+
+To run the examples locally and for development this repository is necessary.
+
+```git clone https://github.com/groupmm/playplot.git```
+
+For a development installation run ```python -m pip install -e .```
+
+All additional dependencies can be installed via ```python -m pip -r requirements.txt```
+
+## Usage
+
+### Examples
+
+For examples see the `examples` folder of this repository.
+These examples need some local data to work properly (except ``minimal``)
+
+Those files are provided for all examples except for ``advanced``.
+See ``examples/example_data/__init__.py`` for which files are additionally required. 
+Members of GroupMM can find the missing files on lin2 under ``/GroupMM/Students/Work_DK/example_data/``
+
+The ``minimal`` and ``basic`` examples don't have additional dependencies.
+``intermediate`` requires ``libfmp`` (can be installed via ``python -m pip install libfmp``)
+``advanced`` has the most dependencies. We recommend installing from the requirements.txt files. (``python -m pip install -r requirements.txt``) 
+
+#### Minimal Example
+
+```python
+import matplotlib.pyplot as plt
+from playplot import Session
+
+# create a Session from the audio data (url not final)
+session = Session.from_file("https://github.com/groupmm/playplot/blob/main/examples/example_data/bach_bwv245_no22_vokalensemble_ilmenau.wav?raw=true")
+
+# decorate the plot function with the session
+@session
+def plot(duration):
+    fig, ax = plt.subplots()
+    ax.plot([0, duration])
+    ax.set_xlabel("number of files played")
+    ax.set_ylabel("time in seconds")
+    return fig, ax
+
+# call the plot function, it will create the plot in another process
+plot(session.duration)
+
+# start the session to enable audio playback
+session.start()
+
+# Wait until all plots are closed (not necessary when running interactive)
+session.join()
+# Check for potential exceptions in the other processes (not necessary when running interactive, an error msg will be displayed)
+session.check()
+```
+
+### Tests
+There are some test script in the `tests` folder, mostly focussing on process management and error handling.
+
+### Docs
+The documentation is built with sphinx and hosted on __GitHub Pages__.
+
+## Contributing
+We welcome any suggestions and contributions.
+For contributing, please create an issue within this GitHub repository.
+Please do not submit a pull request without prior consultation to us.
+
+## Licence
+The code for this package is published under an __MIT licence__.
+This does not apply to the data files in ``examples/example_data``.
+Example file ``bach_bwv245_no22_vokalensemble_ilmenau.wav`` is a recording of Choral No. 22 "Durch Dein Gefängnis" from J.S. Bachs _Johannespassion_, performed by Vokalensemble Ilmenau (conductor: Hans-Jürgen Freitag) at Jakobuskirche Ilmenau, 24.3.2013. Permission granted by the conductor to be used for demo and research purposes only.
+
+## Acknowledgements
+The initial version of this library was created during a research internship of Daniel Keitel within a computer science master's program, under the supervision of Prof. Dr. Meinard Müller, Dr. Christof Weiß and Dr. des. Sebastian Rosenzweig at 
+the International Audio Laboratories Erlangen, which are a joint institution of the Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU) and Fraunhofer Institute for Integrated Circuits IIS. 
+This Python library is closely inspired by the MATLAB tool ``MakePlotPlayable``, implemented by Harald Grohganz and colleagues and part of the MATLAB SM Toolbox [1].
+We also thank the German Research Foundation (DFG) for various research grants that allowed us for conducting fundamental research in music processing.
+
+[1] Meinard Müller, Nanzhu Jiang, and Harald G. Grohganz  
+_SM Toolbox: MATLAB Implementations for Computing and Enhancing Similarity Matrices_  
+Proceedings of 53rd Audio Engineering Society (AES) Conference on Semantic Audio  
+London, UK, 2014.  
+https://www.audiolabs-erlangen.de/resources/MIR/SMtoolbox

docs/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 475cf7a5b5d8e1fcdbfbe8d3cb8a18a1
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_modules/index.html

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Overview: module code &mdash; playplot 0.1.1b1 documentation</title>
+      <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+      <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+
+        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
+        <script src="../_static/jquery.js"></script>
+        <script src="../_static/underscore.js"></script>
+        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
+        <script src="../_static/doctools.js"></script>
+        <script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
+    <script src="../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="../index.html">
+            <img src="../_static/playplot.png" class="logo" alt="Logo"/>
+          </a>
+              <div class="version">
+                0.1.1b1
+              </div>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <ul>
+<li class="toctree-l1"><a class="reference internal" href="../getting-started.html">Getting Started</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../getting-started.html#playplot">Playplot</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api.html">Api Documentation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../the-plot-function.html">The Plotting Function</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../exception-handling.html">Exception Handling</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">Reference</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
+</ul>
+
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">playplot</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
+      <li>Overview: module code</li>
+      <li class="wy-breadcrumbs-aside">
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+
+  <h1>All modules for which code is available</h1>
+<ul><li><a href="playplot/_util.html">playplot._util</a></li>
+<li><a href="playplot/session.html">playplot.session</a></li>
+</ul>
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright .</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>