{
    "info": {
        "author": "Michael Cousins",
        "author_email": "michaelcousins56@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "License :: OSI Approved :: ISC License (ISCL)",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3",
            "Topic :: Multimedia :: Sound/Audio"
        ],
        "description": "\ns3a Decorrelator\n=============\nThe s3a decorrelator is an open-source upmix algorithm written in python.\n\nThe algorithm can also be used to upmix any audio source to any number of channels. The algorithm is blind and the resultant upmix remains mono compatible.\n\nIt was designed to maximise envelopment for diffuse sound objects such as ambience, applause and reverberation but can be used for any source material.\n\nThe python toolbox in this repository includes the tools needed for offline processing of audio files and includes a range of decorrelation filters.\n\n## Introduction\nThe design and validation of the algorithm is fully described in an academic paper that is currently in progress.  Contact m.cousins@surrey.ac.uk for more information.\n\nThe algorithm is formed of two stages. The first stage separates the audio into three components; transients, noise and harmonic content. The second then applies different decorrelation on these components to maximise envelopment whilst minimising the addition of artefacts.\n\n## Examples\nExamples will be available [here](http://www.s3a-spatialaudio.org/research/stream-2/decorrelarion \"s3a Decorrelation Webpage\").\n\n## Prerequisites\nThe decorrelator and toolbox is written in python and requires a python 3 distribution.\nWe recommend the Anaconda distribution and this is compatible with other s3a software including VISR. (Although a conda package for the s3a-decorrelation toolbox is not yet available)\n\nThe package requires: librosa, pysoundfile, scipy, acoustics, matplotlib and pyloudnorm packages. If you use `pip install` to install the package, these dependencies will be installed automatically. \n\nTested with python 3.6 and 3.7.\n\n## Installation\nTo install, open a terminal window (command line on windows) and use the command\n```\npip install s3a-decorrelation-toolbox\n```\n\n## Example\nThe simplest example is \n```\nimport s3a_decorrelation_toolbox.s3a_decorrelator as s3a\n\ns3a.s3a_decorrelator('/folder/input_file.wav',\n'/folder/output_filename.wav', make_mono = True, duration = 10)\n```\nor \n```\nimport s3a_decorrelation_toolbox.s3a_decorrelator as s3a\n\ns3a.s3a_decorrelator('/folder/input_file.wav',\n'/folder/output_filename.wav', preset = 'upmix', make_mono = True, duration = 10)\n```\n\nThis will take a wav called `input_file.wav`, convert it to mono if required (because of the `make_mono = True` argument) and then upmix the first 10 seconds (`duration = 10`) of the mono signal to stereo (the default) and finally saving the output file as `output_filename.wav`. \n\nThe optional `preset = 'upmix'` should probably be used for generic audio upmix purposes where the voice should not be diffuse whereas the default (`preset = 'diffuse'`) is more suited to material such as rain and applause which should be diffuse.\n\nThe file `examples/demo_s3a_decorrelator.py` includes some more demonstrations of general upmix.\n\n## Decorrelation Algoritm\n\nThe design and validation of the algorithm is fully described in an academic paper that is currently in progress but here is a breif overview.\n\n### Background\n\nFor signals to be uncorrelated with each other, the phase relation between the signals need to vary over time. A static phase relationship between signals means that the signals are coherent. Decorrelation methods seek to maximise the randomness of the phse between the two signals. This can be acheived using two mechanisms, phase based and amplitude based. Amplitude based decorrelation is where the input signal is divided between the output signals based on frequency i.e. even frequencies in the one output signal and odd frequencies in the second output signal. Because 100 Hz is incoherent with 101 Hz. this leads to low coherence between the output signals. Phase based methods assume that input signal has a short auto correlation and can therefore is uncorrelated with itself after a delay. By adding different delays to the same signal, the output signals are uncorrelated. One of the issues with both these mechanisms is how they treat transients. Neither mechanism works well for a tranient and the typical artefact is temporal smearing where crisp impulses are replaced by the impulse response of the filters which is not a delta function. Additionally, considering materials such as rain or applause, transients represent specific events such as rain drops or individual claps that come from a single direction and dont need to be decorrelated. It is the fact that these single events come from multiple directions ar random time that leasd them to add to be noise like. But the claps/raindrops individually do not need decorrelation.\n\nThe s3a decorrelator therefore uses a preprocessing stage using a percussive-harmonic-separator to divide the signal into components that are transients, noise and harmonics. These components can then be decorrelated with an appororiate decorrelation method. \n\n### Default Settings\n\nThe default settings used attempt to maximise the amount of decorrelation between loudspeakers by randomly panning transinets to different loudspeakers and using optimal filters for the steady-state components (that can be longer as there is less risk of transinet smearing). This leads to better decorrelation especially for material wher transients should ome from all directions.\n\n\n\n### Presets\n\n`preset = '<preset_name>'` can be used to load some alternative default settings for specific use cases.\n\n`preset = 'diffuse'` uses all default settings and maximises envelopment.\n`preset = 'upmix'` uses the default steady-state decorrelation methods and filter lengths but does not decorrelate the transinets. This is ideal for upmixing any mono to stereo where the mono includes voice. The transients in voice should be grouped together spatially to avoid it sounding very unnatural. Upmix ensures all transients go to all loudspekaers with no decorrelation.\n`preset == 'upmix_mono_LRCSLsRs'` upmixes mono to 5.1 in with loudspeakers ordered L, R, C, Sub, Ls, Rs. All transinets are only routed to the centre channel.\n`preset == 'upmix_stereo_LRCSLsRs'` upmixes stereo to 5.1. The tranisnets remain in the left and right channels. Uncorrelated steady-state components derived from the left input channel remain on the left and visaversa for the right derived channels.\n\n### Other Settings\n\n`make_mono = True'` can be used to force the input audio to mono before upmixing. This is good for testing where you want to input stereo and compare upmixed stereo to the original stereo.\n\n`duration` is the length of the output file in seconds. The decorrelation algorithm is currently not efficient and so for testing purposes, using a short durtion of 10 seconds is sesible.\n\n`num_out_chas` is the number of output channels the output file will have.\n\n`transient_decorrelation_method` is the name of a decorrelation object from decorr_toolbox. e.g. `dt.Lauridsen` to be used to decorrelate the transients.\n`transient_decorrelation_arguments = dict()`  is a dictionary containing arguments to the tranisnet decorrelator. For example `filterLength = 20.5` would  mean the transinent decorrelator would use a length of 20.5 ms\nThe harmonic and noise components have similar arguments named `harmonic_decorrelation_method`, `harmonic_decorrelation_arguments`, `noise_decorrelation_method` and `noise_decorrelation_arguments` .\n\n`transient_routing` and `steady_state_routing` are lists with the output channels for that component. For example         `steady_state_routing' = [0, 1, 2, 4, 5]` would route all noise and harmonic decorrelated outputs to channels 0, 1, 2, 4, and 5 i.e. not to the subwoofer in a 5.1 system. In this case the number of output channels (`num_out_chans = 6`) is greater than the number of decorrelated signals which is overridden by the smaller number of items in the `steady_state_routing` argument.\n\n## Advanced examples\n\nSome upmix examples are included in the demo_s3a_decorrelator script.\n\nHere is another example. We wish to take the ambience from the surround channels of a 5.1 input signal, upmix them to a 22 channel loudspeaker system and add back in the original front channels and the transients to their original channels.\n\n```\nimport soundfile as sf\nimport s3a_decorrelation_toolbox.s3a_decorrelator as s3a\n\naudioFile, fs = sf.read('5.1_input_filename.wav')\n\nsurround_Channels = audioFile[:,[4,5]]\n\naudioOut = s3a.s3a_decorrelator(surround_Channels,                  # input a numpy array instead of filemane string.\n                                    output_filename = None,         # dont write an output file\n                                    'num_out_chans' = 2,             # output has 22 channels\n                                    'transient_routing' = [4, 5],    # Transients go back to the channels they came from\n                                    make_mono = False)              # Upmix from the 2 channels of \n\naudioOut[:, [0, 1 ,2 ,3 ]] += audioFile [:, [0, 1 ,2 ,3 ]] #add back in the non-surround channels\n\nscipy.io.wavfile.write('output_filename.wav', fs, audioOut)\n```\n\n\n# Future Work\nIn the future this code will be proted to a realtime implementation of the separation and filtering stages.\nThe decorrealtor objects in decorr_toolbox will be updated to instead generate filters an outing matricies for the [VISR convolver](https://cvssp.org/data/s3a/public/VISR/visr_installers/0.12.0/macosx/build_py36/doc/userdoc/html/using-standalone-renderers.html#the-matrix-convolver-renderer \"VISR matrix convolver renderer\").\n\n\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/s3a-spatialaudio/decorrelation-python-toolbox",
        "keywords": "",
        "license": "ISC",
        "maintainer": "",
        "maintainer_email": "",
        "name": "s3a-decorrelation-toolbox",
        "package_url": "https://pypi.org/project/s3a-decorrelation-toolbox/",
        "platform": "",
        "project_url": "https://pypi.org/project/s3a-decorrelation-toolbox/",
        "project_urls": {
            "Homepage": "https://github.com/s3a-spatialaudio/decorrelation-python-toolbox"
        },
        "release_url": "https://pypi.org/project/s3a-decorrelation-toolbox/0.2.9/",
        "requires_dist": [
            "numpy (>=1.16.2)",
            "scipy (>=1.2.1)",
            "soundfile (>=0.10.0)",
            "librosa (>=0.6.3)",
            "acoustics (>=0.1.2)",
            "pyloudnorm (>=0.0.1)",
            "matplotlib (>=3.0.2)"
        ],
        "requires_python": "",
        "summary": "Decorrelation algorithm and toolbox for diffuse sound objects and general upmix",
        "version": "0.2.9"
    },
    "last_serial": 4947553,
    "releases": {
        "0.2.8": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "fef39ac5f95e3bcf92a3012e9812dfe6",
                    "sha256": "3220348ac9348d7ac2ade18ae4b93427b65e5d2e102d0b77e5633778a5c12b81"
                },
                "downloads": -1,
                "filename": "s3a_decorrelation_toolbox-0.2.8-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "fef39ac5f95e3bcf92a3012e9812dfe6",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 15305,
                "upload_time": "2019-03-15T14:14:27",
                "url": "https://files.pythonhosted.org/packages/90/4a/c7f5e4ffb68422acfa0126e5a595f01c198b9dfea7fed8f6f6089ae8cd53/s3a_decorrelation_toolbox-0.2.8-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "445158025e42c55af392bc885ca8d066",
                    "sha256": "be671d6b26f5460414aa16c336cd6a78d3f2a53c394af000f7cafc799829b193"
                },
                "downloads": -1,
                "filename": "s3a_decorrelation_toolbox-0.2.8.tar.gz",
                "has_sig": false,
                "md5_digest": "445158025e42c55af392bc885ca8d066",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15892,
                "upload_time": "2019-03-15T14:14:29",
                "url": "https://files.pythonhosted.org/packages/fd/17/396665bb49b3cbc504f8a760e1e1cee40c75016d78d14da690900e77f452/s3a_decorrelation_toolbox-0.2.8.tar.gz"
            }
        ],
        "0.2.9": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c4266d691c300707f6c911b54395f4c0",
                    "sha256": "156f3574985aacebae94c26e696e5690d1b3aed16e0c18ac247933c1ccc5f45c"
                },
                "downloads": -1,
                "filename": "s3a_decorrelation_toolbox-0.2.9-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "c4266d691c300707f6c911b54395f4c0",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 15421,
                "upload_time": "2019-03-16T12:56:28",
                "url": "https://files.pythonhosted.org/packages/f8/bc/020e4f6ec3361121a82ab8d1ca3c0051defbe2e921076a94f24058437a06/s3a_decorrelation_toolbox-0.2.9-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "e70cc1f383a9d62e180afa25d1c8ba8d",
                    "sha256": "ca38b5763249b4f5a98b4ecce85d6c54415ef18c0a2c6ff70ea8383ee9e4f340"
                },
                "downloads": -1,
                "filename": "s3a_decorrelation_toolbox-0.2.9.tar.gz",
                "has_sig": false,
                "md5_digest": "e70cc1f383a9d62e180afa25d1c8ba8d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16137,
                "upload_time": "2019-03-16T12:56:30",
                "url": "https://files.pythonhosted.org/packages/07/b7/50a87f4357d0a3d976e415e2c45d9f8fad91101dc20b2214224c92b11b8a/s3a_decorrelation_toolbox-0.2.9.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "c4266d691c300707f6c911b54395f4c0",
                "sha256": "156f3574985aacebae94c26e696e5690d1b3aed16e0c18ac247933c1ccc5f45c"
            },
            "downloads": -1,
            "filename": "s3a_decorrelation_toolbox-0.2.9-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c4266d691c300707f6c911b54395f4c0",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 15421,
            "upload_time": "2019-03-16T12:56:28",
            "url": "https://files.pythonhosted.org/packages/f8/bc/020e4f6ec3361121a82ab8d1ca3c0051defbe2e921076a94f24058437a06/s3a_decorrelation_toolbox-0.2.9-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "e70cc1f383a9d62e180afa25d1c8ba8d",
                "sha256": "ca38b5763249b4f5a98b4ecce85d6c54415ef18c0a2c6ff70ea8383ee9e4f340"
            },
            "downloads": -1,
            "filename": "s3a_decorrelation_toolbox-0.2.9.tar.gz",
            "has_sig": false,
            "md5_digest": "e70cc1f383a9d62e180afa25d1c8ba8d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 16137,
            "upload_time": "2019-03-16T12:56:30",
            "url": "https://files.pythonhosted.org/packages/07/b7/50a87f4357d0a3d976e415e2c45d9f8fad91101dc20b2214224c92b11b8a/s3a_decorrelation_toolbox-0.2.9.tar.gz"
        }
    ]
}