diff --git a/docs/source/basics.rst b/docs/source/basics.rst new file mode 100644 index 0000000..0554d66 --- /dev/null +++ b/docs/source/basics.rst @@ -0,0 +1,21 @@ +Basic usage +---------------------------------------- +In order to compute audio features regarding a certain track, you just have to +create an instance of your desired track object and then call its +:code:`extract()` method with the path to an audio file. Considre the following +example: + +.. code-block:: python + + from comsar.tracks import TimbreTrack + + tt = TimbreTrack() + res = tt.extract('path/to/my_audio.wav') + res.to_pickle('my_features.pkl') + +The first line imports the desired Track object, in this case a +:code:`TimbreTrack`. The third line creates a :code:`TimbreTrack` instance +with the name :code:`tt`. The fourth line calls the :code:`extract` method of +:code:`tt` and passes it the path to an actual audio file. comsar then +processes the audio file and makes the results available under the name +:code:`res`. The fifths line eventually saves the results to disc. diff --git a/docs/source/index.rst b/docs/source/index.rst index e33f8ed..96d916c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,20 +1,34 @@ -.. comsar rtd test documentation master file, created by - sphinx-quickstart on Tue Apr 20 15:10:22 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. COMSAR documentation master file, created by + sphinx-quickstart on Fri Feb 19 07:54:14 2021. -Welcome to the rtd-config-test documentation! -============================================== +Computational Music and Sound Archiving +======================================= +The Computational Music and Sound Archiving system provides high-level audio +feature extraction facilities for multi-viewpoint music similarity analysis. -.. toctree:: - :maxdepth: 2 - :caption: Contents: +Music similarity is hard to analyse. A viewpoint highlights certain aspects of +musical perception. Asking for similarity regarding pitch requires another +viewpoint than asking for rhythm similarity. + +COMSAR combines pre-selected low-level audio features to *Track* +objects, which represent a viewpoint. +.. toctree:: + :maxdepth: 2 + :caption: Contents + + install + basics + tracks + + +Open source +---------------------------------------- +comsar is an open source project. It is published under the permissive `BSD +3-Clause License`_. You may change and republish the code for any personal or +commercial project. The `comsar source code`_ is available on GitHub. -Indices and tables -================== +.. _BSD 3-Clause License: https://opensource.org/licenses/BSD-3-Clause -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. _comsar source code: https://github.com/ifsm/comsar diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000..a9f6239 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,29 @@ +*************************************** +Installation +*************************************** + + +Installation from PyPi +======================================== +comsar is available on PyPi. Simply run the following command in your favorite +terminal emulator:: + + pip install comsar + + +Installation from source +======================================== +Installation from source is done in two steps: + +* If you do not have git installed, simply navigate to the source code + repository, click on the green "Code" button and then select "Download ZIP". + Otherwise, clone the source code with git:: + + git clone https://github.com/ifsm/comsar + + +* Once the code is downloaded, change to the comsar root directory and advise Python to install + the pacakge:: + + cd path/to/comsar + python3 -m pip install . diff --git a/docs/source/tracks.rst b/docs/source/tracks.rst new file mode 100644 index 0000000..0413900 --- /dev/null +++ b/docs/source/tracks.rst @@ -0,0 +1,19 @@ +**************************************** +Track sytem +**************************************** + +PitchTrack +======================================== + +RhythmTrack +======================================== + +TimbreTrack +======================================== + +.. autoclass:: comsar.tracks.TimbreTrack + :members: + +FormTrack +======================================== +Implementation of the FormTrack is planed.