McSinyx
/
palace
mirror of https://github.com/McSinyx/palace
1
1
Fork 0
Code Issues Releases Activity

Write source manipulation tutorial

This commit is contained in:
Huy-Ngo 2020-05-25 21:19:42 +07:00 committed by Nguyễn Gia Phong
parent a0b4a90f79
commit 08408c56c7
52 changed files with 11541 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doctrees/contributing.doctree
View File

Binary file not shown.

BIN
doctrees/copying.doctree
View File

Binary file not shown.

BIN
doctrees/design.doctree
View File

Binary file not shown.

BIN
doctrees/environment.pickle
View File

Binary file not shown.

BIN
doctrees/index.doctree
View File

Binary file not shown.

BIN
doctrees/installation.doctree
View File

Binary file not shown.

BIN
doctrees/reference/buffer.doctree
View File

Binary file not shown.

BIN
doctrees/reference/context.doctree
View File

Binary file not shown.

BIN
doctrees/reference/decoder.doctree
View File

Binary file not shown.

BIN
doctrees/reference/device.doctree
View File

Binary file not shown.

BIN
doctrees/reference/effect.doctree
View File

Binary file not shown.

BIN
doctrees/reference/file-io.doctree
View File

Binary file not shown.

BIN
doctrees/reference/index.doctree
View File

Binary file not shown.

BIN
doctrees/reference/source.doctree
View File

Binary file not shown.

BIN
doctrees/tutorial/context.doctree
View File

Binary file not shown.

BIN
doctrees/tutorial/index.doctree
View File

Binary file not shown.

BIN
doctrees/tutorial/play-audio.doctree
View File

Binary file not shown.

2
html/.buildinfo
View File

@ -1,4 +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: 6ed1cb47293b105da06b6b123fa9eb60
config: 15f696dd8f7d3d70ce592a5e4a09ce3d
tags: 645f666f9bcd5a90fca523b33c5a78b7

2
html/_sources/index.rst.txt
View File

@ -7,7 +7,7 @@ for audio rendering using OpenAL:
* 3D positional rendering, with HRTF_ support for stereo systems
* Environmental effects: reverb, atmospheric air absorption,
sound occlusion and obstruction
* Out-of-the-box codec support:
* Out-of-the-box codec support: FLAC, MP3, Ogg Vorbis, Opus, WAV, AIFF, etc.
Palace wraps around the C++ interface alure_ using Cython_ for a safe and
convenient interface with type hinting, data descriptors and context managers,

2
html/_sources/tutorial/index.rst.txt
View File

@ -8,8 +8,8 @@ This tutorial will guide you on:
context
play-audio
source
.. comment these to add later
Moving sources
Adding effects
Customize decoder
Generate sounds

82
html/_sources/tutorial/source.rst.txt Normal file
View File

@ -0,0 +1,82 @@
Source Manipulation
===================
.. currentmodule:: palace
We have created a source in the last section.
As said previously, its properties can be manipulated to create wanted effects.
Moving the Source
-----------------
Changing :py:attr:`Source.position` is one of the most noticeable,
but first, we have to enable spatialization via :py:attr:`Source.spatialize`.
.. code-block:: python
from time import sleep
from palace import Device, Context, Source, decode
with Device() as device, Context(device) as context, Source() as source:
source.spatialize = True
decoder = decode('some_audio.ogg')
decoder.play(12000, 4, source)
while source.playing:
sleep(0.025)
context.update()
Now, we can set the position of the source in this virtual 3D space.
The position is a 3-tuple indicating the coordinate of the source.
The axes are aligned according to the normal coordinate system:
- The x-axis goes from left to right
- The y-axis goes from below to above
- The z-axis goes from front to back
For example, this will set the source above the listener::
src.position = 0, 1, 0
.. note::
For this too work for stereo, you have to have HRTF enabled.
You can check that via :py:attr:`Device.current_hrtf`.
You can as well use a function to move the source automatically by writing
a function that generate positions. A simple example is circular motion.
.. code-block:: python
from itertools import takewhile, count
...
for i in takewhile(src.playing, count(step=0.025)):
source.position = sin(i), 0, cos(-i)
...
A more well-written example of this can be found `in our repository`_.
Speed and Pitch
---------------
Modifying :py:attr:`pitch` changes the playing speed, effectively changing
pitch. Pitch can be any positive number.
.. code-block:: python
src.pitch = 2 # high pitch
src.pitch = 0.4 # low pitch
Air Absorption Factor
---------------------
:py:attr:`Source.air_absorption_factor` simulates atmospheric high-frequency
air absorption. Higher values simulate foggy air and lower values simulate
drier air.
.. code-block:: python
src.air_absorption_factor = 9 # very high humidity
src.air_absorption_factor = 0 # dry air (default)
.. _in our repository:
https://github.com/McSinyx/palace/blob/master/examples/palace-hrtf.py

141
html/_static/basic.css
View File

@ -15,6 +15,12 @@ div.clearer {
clear: both;
}
div.section::after {
display: block;
content: '';
clear: left;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
@ -316,21 +322,27 @@ img.align-default, .figure.align-default {
div.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px 7px 0 7px;
padding: 7px;
background-color: #ffe;
width: 40%;
float: right;
clear: right;
overflow-x: auto;
}
p.sidebar-title {
font-weight: bold;
}
div.admonition, div.topic, blockquote {
clear: left;
}
/* -- topics ---------------------------------------------------------------- */
div.topic {
border: 1px solid #ccc;
padding: 7px 7px 0 7px;
padding: 7px;
margin: 10px 0 10px 0;
}
@ -352,10 +364,6 @@ div.admonition dt {
font-weight: bold;
}
div.admonition dl {
margin-bottom: 0;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
@ -366,9 +374,28 @@ div.body p.centered {
margin-top: 25px;
}
/* -- content of sidebars/topics/admonitions -------------------------------- */
div.sidebar > :last-child,
div.topic > :last-child,
div.admonition > :last-child {
margin-bottom: 0;
}
div.sidebar::after,
div.topic::after,
div.admonition::after,
blockquote::after {
display: block;
content: '';
clear: both;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
margin-top: 10px;
margin-bottom: 10px;
border: 0;
border-collapse: collapse;
}
@ -416,13 +443,13 @@ table.citation td {
border-bottom: none;
}
th > p:first-child,
td > p:first-child {
th > :first-child,
td > :first-child {
margin-top: 0px;
}
th > p:last-child,
td > p:last-child {
th > :last-child,
td > :last-child {
margin-bottom: 0px;
}
@ -468,6 +495,10 @@ table.field-list td, table.field-list th {
/* -- hlist styles ---------------------------------------------------------- */
table.hlist {
margin: 1em 0;
}
table.hlist td {
vertical-align: top;
}
@ -495,17 +526,37 @@ ol.upperroman {
list-style: upper-roman;
}
li > p:first-child {
:not(li) > ol > li:first-child > :first-child,
:not(li) > ul > li:first-child > :first-child {
margin-top: 0px;
}
li > p:last-child {
:not(li) > ol > li:last-child > :last-child,
:not(li) > ul > li:last-child > :last-child {
margin-bottom: 0px;
}
ol.simple ol p,
ol.simple ul p,
ul.simple ol p,
ul.simple ul p {
margin-top: 0;
}
ol.simple > li:not(:first-child) > p,
ul.simple > li:not(:first-child) > p {
margin-top: 0;
}
ol.simple p,
ul.simple p {
margin-bottom: 0;
}
dl.footnote > dt,
dl.citation > dt {
float: left;
margin-right: 0.5em;
}
dl.footnote > dd,
@ -546,7 +597,7 @@ dl {
margin-bottom: 15px;
}
dd > p:first-child {
dd > :first-child {
margin-top: 0px;
}
@ -560,6 +611,11 @@ dd {
margin-left: 30px;
}
dl > dd:last-child,
dl > dd:last-child > :last-child {
margin-bottom: 0;
}
dt:target, span.highlighted {
background-color: #fbe54e;
}
@ -637,6 +693,10 @@ pre {
overflow-y: hidden; /* fixes display issues on Chrome browsers */
}
pre, div[class*="highlight-"] {
clear: both;
}
span.pre {
-moz-hyphens: none;
-ms-hyphens: none;
@ -644,22 +704,57 @@ span.pre {
hyphens: none;
}
div[class*="highlight-"] {
margin: 1em 0;
}
td.linenos pre {
padding: 5px 0px;
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
margin-left: 0.5em;
display: block;
}
table.highlighttable tbody {
display: block;
}
table.highlighttable tr {
display: flex;
}
table.highlighttable td {
padding: 0 0.5em 0 0.5em;
margin: 0;
padding: 0;
}
table.highlighttable td.linenos {
padding-right: 0.5em;
}
table.highlighttable td.code {
flex: 1;
overflow: hidden;
}
.highlight .hll {
display: block;
}
div.highlight pre,
table.highlighttable pre {
margin: 0;
}
div.code-block-caption + div {
margin-top: 0;
}
div.code-block-caption {
margin-top: 1em;
padding: 2px 5px;
font-size: small;
}
@ -668,10 +763,7 @@ div.code-block-caption code {
background-color: transparent;
}
div.code-block-caption + div > div.highlight > pre {
margin-top: 0;
}
table.highlighttable td.linenos,
div.doctest > div.highlight span.gp { /* gp: Generic.Prompt */
user-select: none;
}
@ -685,11 +777,7 @@ div.code-block-caption span.caption-text {
}
div.literal-block-wrapper {
padding: 1em 1em 0;
}
div.literal-block-wrapper div.highlight {
margin: 0;
margin: 1em 0;
}
code.descname {
@ -740,8 +828,7 @@ span.eqno {
}
span.eqno a.headerlink {
position: relative;
left: 0px;
position: absolute;
z-index: 1;
}

2
html/_static/documentation_options.js
View File

@ -1,6 +1,6 @@
var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '0.2.0',
VERSION: '0.2.1',
LANGUAGE: 'None',
COLLAPSE_INDEX: false,
BUILDER: 'html',

10872
html/_static/jquery-3.5.1.js vendored Normal file
View File

File diff suppressed because it is too large Load Diff

4
html/_static/jquery.js vendored
View File

File diff suppressed because one or more lines are too long

3
html/_static/searchtools.js
View File

@ -166,8 +166,7 @@ var Search = {
objectterms.push(tmp[i].toLowerCase());
}
if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i].match(/^\d+$/) ||
tmp[i] === "") {
if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") {
// skip this "word"
continue;
}

5
html/contributing.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Getting Involved &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Getting Involved &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
@ -316,7 +317,7 @@ except after the final sentence.</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

5
html/copying.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Copying &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Copying &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
@ -208,7 +209,7 @@ extreamly quickly to obsolete Cython-related issues.</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

5
html/design.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Design Principles &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Design Principles &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
@ -283,7 +284,7 @@ implementation as a pure Python class and <a class="reference internal" href="#g
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

6
html/genindex.html
View File

@ -1,11 +1,11 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Index &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Index &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
@ -710,7 +710,7 @@
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>

8
html/index.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Overview &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Overview &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
@ -103,7 +104,7 @@ for audio rendering using OpenAL:</p>
<li><p>3D positional rendering, with <a class="reference external" href="https://en.wikipedia.org/wiki/Head-related_transfer_function">HRTF</a> support for stereo systems</p></li>
<li><p>Environmental effects: reverb, atmospheric air absorption,
sound occlusion and obstruction</p></li>
<li><p>Out-of-the-box codec support:</p></li>
<li><p>Out-of-the-box codec support: FLAC, MP3, Ogg Vorbis, Opus, WAV, AIFF, etc.</p></li>
</ul>
<p>Palace wraps around the C++ interface <a class="reference external" href="https://github.com/kcat/alure">alure</a> using <a class="reference external" href="https://cython.org">Cython</a> for a safe and
convenient interface with type hinting, data descriptors and context managers,
@ -121,6 +122,7 @@ following <span class="target" id="index-0"></span><a class="pep reference exter
<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial/context.html">Context Creation</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial/play-audio.html">Play an Audio</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial/source.html">Source Manipulation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="reference/index.html">Reference</a><ul>
@ -187,7 +189,7 @@ following <span class="target" id="index-0"></span><a class="pep reference exter
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

5
html/installation.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Installation &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Installation &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
@ -161,7 +162,7 @@ Palace can then be compiled and installed by running:</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

BIN
html/objects.inv
View File

Binary file not shown.

12
html/reference/buffer.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Resource Caching &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Resource Caching &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -203,15 +204,16 @@ By default <cite>current_context()</cite> is used.</p></li>
<dt id="palace.Buffer.loop_points">
<code class="sig-name descname">loop_points</code><a class="headerlink" href="#palace.Buffer.loop_points" title="Permalink to this definition"></a></dt>
<dd><p>Loop points for looping sources.</p>
<p>If the <cite>AL_SOFT_loop_points</cite> extension is not supported by the
<p>If <cite>AL_SOFT_loop_points</cite> extension is not supported by the
current context, <cite>start = 0</cite> and <cite>end = length</cite> respectively.
Otherwise, <cite>start &lt; end &lt;= length</cite>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>start</strong> (<em>int</em>) – Starting point, in sample frames (inclusive).</p></li>
<li><p><strong>end</strong> (<em>int</em>) – Ending point, in sample frames (exclusive).</p></li>
</ul>
</p>
</dd>
</dl>
<p class="rubric">Notes</p>
@ -334,7 +336,7 @@ an exception.</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

23
html/reference/context.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Audio Library Contexts &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Audio Library Contexts &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -179,8 +180,8 @@ such as sources, buffers and effects.</p>
<dt id="palace.Context.available_resamplers">
<em class="property">property </em><code class="sig-name descname">available_resamplers</code><a class="headerlink" href="#palace.Context.available_resamplers" title="Permalink to this definition"></a></dt>
<dd><p>The list of resamplers supported by the context.</p>
<p>If the <cite>AL_SOFT_source_resampler</cite> extension is unsupported
this will be an empty list, otherwise there would be
<p>If <cite>AL_SOFT_source_resampler</cite> extension is unsupported,
this will be an empty list. Otherwise there would be
at least one entry.</p>
<p>This method require the context to be current.</p>
</dd></dl>
@ -189,8 +190,8 @@ at least one entry.</p>
<dt id="palace.Context.default_resampler_index">
<em class="property">property </em><code class="sig-name descname">default_resampler_index</code><a class="headerlink" href="#palace.Context.default_resampler_index" title="Permalink to this definition"></a></dt>
<dd><p>The context’s default resampler index.</p>
<p>If the <cite>AL_SOFT_source_resampler</cite> extension is unsupported
the resampler list will be empty and this will return 0.</p>
<p>If <cite>AL_SOFT_source_resampler</cite> extension is unsupported,
this will return 0.</p>
<p>If you try to access the resampler list with this index
without extension, undefined behavior will occur
(accessing an out of bounds array index).</p>
@ -382,7 +383,7 @@ following Python buffer protocol.</p>
<code class="sig-name descname">device_disconnected</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">device</span><span class="p">:</span> <span class="n"><a class="reference internal" href="device.html#palace.Device" title="palace.Device">palace.Device</a></span></em><span class="sig-paren">)</span> &#x2192; None<a class="headerlink" href="#palace.MessageHandler.device_disconnected" title="Permalink to this definition"></a></dt>
<dd><p>Handle disconnected device messages.</p>
<p>This is called when the given device has been disconnected and
is no longer usable for output. As per the <cite>ALC_EXT_disconnect</cite>
is no longer usable for output. As per <cite>ALC_EXT_disconnect</cite>
specification, disconnected devices remain valid, however all
playing sources are automatically stopped, any sources that are
attempted to play will immediately stop, and new contexts may
@ -391,7 +392,7 @@ not be created on the device.</p>
<p>Connection status is checked during <cite>Context.update</cite> calls, so
method must be called regularly to be notified when a device is
disconnected. This method may not be called if the device lacks
support for the <cite>ALC_EXT_disconnect</cite> extension.</p>
support for <cite>ALC_EXT_disconnect</cite> extension.</p>
</dd></dl>
<dl class="py method">
@ -461,9 +462,9 @@ extension to be available.</p>
<dl class="py function">
<dt id="palace.thread_local">
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">thread_local</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">state</span><span class="p">:</span> <span class="n">bool</span></em><span class="sig-paren">)</span> &#x2192; Iterator[None]<a class="headerlink" href="#palace.thread_local" title="Permalink to this definition"></a></dt>
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">thread_local</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">state</span><span class="p">:</span> <span class="n">bool</span></em><span class="sig-paren">)</span> &#x2192; Iterator<span class="p">[</span>None<span class="p">]</span><a class="headerlink" href="#palace.thread_local" title="Permalink to this definition"></a></dt>
<dd><p>Return a context manager controlling preference of local thread.</p>
<p>Effectively, it sets the fallback value for the <cite>thread</cite> argument
<p>Effectively, it sets fallback value for <cite>thread</cite> argument
for <cite>current_context</cite> and <cite>use_context</cite>.</p>
<p>Initially, globally current <cite>Context</cite> is preferred.</p>
</dd></dl>
@ -532,7 +533,7 @@ auxiliary source sends.</p>
<dl class="py data">
<dt id="palace.distance_models">
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">distance_models</code><em class="property">: Tuple[str, ...]</em><a class="headerlink" href="#palace.distance_models" title="Permalink to this definition"></a></dt>
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">distance_models</code><em class="property">: Tuple<span class="p">[</span>str<span class="p">, </span><span class="p">…</span><span class="p">]</span></em><a class="headerlink" href="#palace.distance_models" title="Permalink to this definition"></a></dt>
<dd><p>Names of available distance models.</p>
</dd></dl>
@ -565,7 +566,7 @@ auxiliary source sends.</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

23
html/reference/decoder.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Audio Streams &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Audio Streams &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -175,11 +176,12 @@ please call the module-level <cite>decode</cite> function instead.</p>
<em class="property">property </em><code class="sig-name descname">loop_points</code><a class="headerlink" href="#palace.Decoder.loop_points" title="Permalink to this definition"></a></dt>
<dd><p>Loop points in sample frames.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>start</strong> (<em>int</em>) – Inclusive starting loop point.</p></li>
<li><p><strong>end</strong> (<em>int</em>) – Exclusive starting loop point.</p></li>
</ul>
</p>
</dd>
</dl>
<p class="rubric">Notes</p>
@ -239,7 +241,7 @@ the end of the audio has been reached.</p>
<dl class="py method">
<dt id="palace.Decoder.seek">
<code class="sig-name descname">seek</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">pos</span><span class="p">:</span> <span class="n">int</span></em><span class="sig-paren">)</span> &#x2192; bool<a class="headerlink" href="#palace.Decoder.seek" title="Permalink to this definition"></a></dt>
<dd><p>Seek to pos, specified in sample frames.</p>
<dd><p>Seek to <cite>pos</cite>, specified in sample frames.</p>
<p>Return if the seek was successful.</p>
</dd></dl>
@ -279,7 +281,7 @@ lexicographical order, then fallback to the internal ones.</p>
<dl class="py class">
<dt id="palace.BaseDecoder">
<em class="property">class </em><code class="sig-prename descclassname">palace.</code><code class="sig-name descname">BaseDecoder</code><a class="headerlink" href="#palace.BaseDecoder" title="Permalink to this definition"></a></dt>
<em class="property">class </em><code class="sig-prename descclassname">palace.</code><code class="sig-name descname">BaseDecoder</code><span class="sig-paren">(</span><em class="sig-param"><span class="o">*</span><span class="n">args</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="headerlink" href="#palace.BaseDecoder" title="Permalink to this definition"></a></dt>
<dd><p>Audio decoder interface.</p>
<p>Applications may derive from this, implement necessary methods,
and use it in places the API wants a <cite>BaseDecoder</cite> object.</p>
@ -309,11 +311,12 @@ and use it in places the API wants a <cite>BaseDecoder</cite> object.</p>
<em class="property">abstract property </em><code class="sig-name descname">loop_points</code><a class="headerlink" href="#palace.BaseDecoder.loop_points" title="Permalink to this definition"></a></dt>
<dd><p>Loop points in sample frames.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>start</strong> (<em>int</em>) – Inclusive starting loop point.</p></li>
<li><p><strong>end</strong> (<em>int</em>) – Exclusive starting loop point.</p></li>
</ul>
</p>
</dd>
</dl>
<p class="rubric">Notes</p>
@ -349,13 +352,13 @@ the end of the audio has been reached.</p>
<h2>Miscellaneous<a class="headerlink" href="#miscellaneous" title="Permalink to this headline"></a></h2>
<dl class="py data">
<dt id="palace.sample_types">
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">sample_types</code><em class="property">: Tuple[str, ...]</em><a class="headerlink" href="#palace.sample_types" title="Permalink to this definition"></a></dt>
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">sample_types</code><em class="property">: Tuple<span class="p">[</span>str<span class="p">, </span><span class="p">…</span><span class="p">]</span></em><a class="headerlink" href="#palace.sample_types" title="Permalink to this definition"></a></dt>
<dd><p>Names of available sample types.</p>
</dd></dl>
<dl class="py data">
<dt id="palace.channel_configs">
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">channel_configs</code><em class="property">: Tuple[str, ...]</em><a class="headerlink" href="#palace.channel_configs" title="Permalink to this definition"></a></dt>
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">channel_configs</code><em class="property">: Tuple<span class="p">[</span>str<span class="p">, </span><span class="p">…</span><span class="p">]</span></em><a class="headerlink" href="#palace.channel_configs" title="Permalink to this definition"></a></dt>
<dd><p>Names of available channel configurations.</p>
</dd></dl>
@ -413,7 +416,7 @@ the end of the audio has been reached.</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

16
html/reference/device.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Audio Devices &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Audio Devices &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -182,8 +183,7 @@ extension to retrieve the audio device’s real clock.</p>
<dt id="palace.Device.efx_version">
<em class="property">property </em><code class="sig-name descname">efx_version</code><a class="headerlink" href="#palace.Device.efx_version" title="Permalink to this definition"></a></dt>
<dd><p>EFX version supported by this device.</p>
<p>If the <cite>ALC_EXT_EFX</cite> extension is unsupported,
this will be <cite>(0, 0)</cite>.</p>
<p>If <cite>ALC_EXT_EFX</cite> extension is unsupported, this will be (0, 0).</p>
</dd></dl>
<dl class="py method">
@ -196,7 +196,7 @@ this will be <cite>(0, 0)</cite>.</p>
<dt id="palace.Device.hrtf_enabled">
<em class="property">property </em><code class="sig-name descname">hrtf_enabled</code><a class="headerlink" href="#palace.Device.hrtf_enabled" title="Permalink to this definition"></a></dt>
<dd><p>Whether HRTF is enabled on the device.</p>
<p>If the <cite>ALC_SOFT_HRTF</cite> extension is unavailable,
<p>If <cite>ALC_SOFT_HRTF</cite> extension is unavailable,
this will return False although there could still be
HRTF applied at a lower hardware level.</p>
</dd></dl>
@ -207,7 +207,7 @@ HRTF applied at a lower hardware level.</p>
<dd><p>List of available HRTF names.</p>
<p>The order is retained from OpenAL, such that the index of
a given name is the ID to use with <cite>ALC_HRTF_ID_SOFT</cite>.</p>
<p>If the <cite>ALC_SOFT_HRTF</cite> extension is unavailable,
<p>If <cite>ALC_SOFT_HRTF</cite> extension is unavailable,
this will be an empty list.</p>
</dd></dl>
@ -230,7 +230,7 @@ this will be an empty list.</p>
<dd><p>Pause device processing and stop contexts’ updates.</p>
<p>Multiple calls are allowed but it is not reference counted,
so the device will resume after one <cite>resume_dsp</cite> call.</p>
<p>This requires the <cite>ALC_SOFT_pause_device</cite> extension.</p>
<p>This requires <cite>ALC_SOFT_pause_device</cite> extension.</p>
</dd></dl>
<dl class="py method">
@ -250,7 +250,7 @@ so the device will resume after one <cite>resume_dsp</cite> call.</p>
<dt id="palace.Device.reset">
<code class="sig-name descname">reset</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">attrs</span><span class="p">:</span> <span class="n">Dict<span class="p">[</span>int<span class="p">, </span>int<span class="p">]</span></span></em><span class="sig-paren">)</span> &#x2192; None<a class="headerlink" href="#palace.Device.reset" title="Permalink to this definition"></a></dt>
<dd><p>Reset the device, using the specified attributes.</p>
<p>If the <cite>ALC_SOFT_HRTF</cite> extension is unavailable,
<p>If <cite>ALC_SOFT_HRTF</cite> extension is unavailable,
this will be a no-op.</p>
</dd></dl>
@ -315,7 +315,7 @@ this will be a no-op.</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

20
html/reference/effect.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Environmental Effects &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Environmental Effects &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -137,7 +138,7 @@ By default <cite>current_context()</cite> is used.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="#palace.ReverbEffect" title="palace.ReverbEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReverbEffect</span></code></a></dt><dd><p>EAXReverb effect</p>
<dt><a class="reference internal" href="#palace.ReverbEffect" title="palace.ReverbEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReverbEffect</span></code></a></dt><dd><p>Environmental reverberation effect</p>
</dd>
<dt><a class="reference internal" href="#palace.ChorusEffect" title="palace.ChorusEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ChorusEffect</span></code></a></dt><dd><p>Chorus effect</p>
</dd>
@ -179,6 +180,11 @@ it will be removed first.</p>
<dt id="palace.ChorusEffect">
<em class="property">class </em><code class="sig-prename descclassname">palace.</code><code class="sig-name descname">ChorusEffect</code><a class="headerlink" href="#palace.ChorusEffect" title="Permalink to this definition"></a></dt>
<dd><p>Chorus effect.</p>
<p>The chorus effect essentially replays the input audio accompanied
by another slightly delayed version of the signal, creating
a “doubling” effect. This was originally intended to emulate
the effect of several musicians playing the same notes
simultaneously, to create a thicker, more satisfying sound.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
@ -232,16 +238,14 @@ By default <cite>current_context()</cite> is used.</p></li>
<h2>Reverb Effect<a class="headerlink" href="#reverb-effect" title="Permalink to this headline"></a></h2>
<dl class="py data">
<dt id="palace.reverb_preset_names">
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">reverb_preset_names</code><em class="property">: Tuple[str, ...]</em><a class="headerlink" href="#palace.reverb_preset_names" title="Permalink to this definition"></a></dt>
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">reverb_preset_names</code><em class="property">: Tuple<span class="p">[</span>str<span class="p">, </span><span class="p">…</span><span class="p">]</span></em><a class="headerlink" href="#palace.reverb_preset_names" title="Permalink to this definition"></a></dt>
<dd><p>Names of predefined reverb effect presets in lexicographical order.</p>
</dd></dl>
<dl class="py class">
<dt id="palace.ReverbEffect">
<em class="property">class </em><code class="sig-prename descclassname">palace.</code><code class="sig-name descname">ReverbEffect</code><a class="headerlink" href="#palace.ReverbEffect" title="Permalink to this definition"></a></dt>
<dd><p>EAXReverb effect.</p>
<p>It will automatically downgrade to the Standard Reverb effect
if EAXReverb effect is not supported.</p>
<dd><p>Environmental reverberation effect.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
@ -266,7 +270,7 @@ By default <cite>current_context()</cite> is used.</p></li>
<dl class="py attribute">
<dt id="palace.ReverbEffect.decay_hf_limit">
<code class="sig-name descname">decay_hf_limit</code><a class="headerlink" href="#palace.ReverbEffect.decay_hf_limit" title="Permalink to this definition"></a></dt>
<dd><p>High frequency decay limit.</p>
<dd><p>Whether to limit high frequency decay.</p>
</dd></dl>
<dl class="py attribute">
@ -432,7 +436,7 @@ By default <cite>current_context()</cite> is used.</p></li>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

9
html/reference/file-io.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>File I/O Interface &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>File I/O Interface &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -120,14 +121,14 @@
<dl class="py function">
<dt id="palace.use_fileio">
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">use_fileio</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">factory</span><span class="p">:</span> <span class="n">Optional<span class="p">[</span>Callable<span class="p">[</span><span class="p">[</span>str<span class="p">]</span><span class="p">, </span>FileIO<span class="p">]</span><span class="p">]</span></span></em>, <em class="sig-param"><span class="n">buffer_size</span><span class="p">:</span> <span class="n">int</span> <span class="o">=</span> <span class="default_value">8192</span></em><span class="sig-paren">)</span> &#x2192; None<a class="headerlink" href="#palace.use_fileio" title="Permalink to this definition"></a></dt>
<code class="sig-prename descclassname">palace.</code><code class="sig-name descname">use_fileio</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">factory</span><span class="p">:</span> <span class="n">Optional<span class="p">[</span>Callable<span class="p">[</span><span class="p">[</span>str<span class="p">]</span><span class="p">, </span><a class="reference internal" href="#palace.FileIO" title="palace.FileIO">FileIO</a><span class="p">]</span><span class="p">]</span></span></em>, <em class="sig-param"><span class="n">buffer_size</span><span class="p">:</span> <span class="n">int</span> <span class="o">=</span> <span class="default_value">8192</span></em><span class="sig-paren">)</span> &#x2192; None<a class="headerlink" href="#palace.use_fileio" title="Permalink to this definition"></a></dt>
<dd><p>Set the file I/O factory instance to be used by audio decoders.</p>
<p>If <cite>factory=None</cite> is provided, revert to the default.</p>
</dd></dl>
<dl class="py class">
<dt id="palace.FileIO">
<em class="property">class </em><code class="sig-prename descclassname">palace.</code><code class="sig-name descname">FileIO</code><span class="sig-paren">(</span><em class="sig-param"><span class="o">*</span><span class="n">args</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwargs</span></em><span class="sig-paren">)</span><a class="headerlink" href="#palace.FileIO" title="Permalink to this definition"></a></dt>
<em class="property">class </em><code class="sig-prename descclassname">palace.</code><code class="sig-name descname">FileIO</code><span class="sig-paren">(</span><em class="sig-param"><span class="o">*</span><span class="n">args</span></em>, <em class="sig-param"><span class="o">**</span><span class="n">kwds</span></em><span class="sig-paren">)</span><a class="headerlink" href="#palace.FileIO" title="Permalink to this definition"></a></dt>
<dd><p>File I/O protocol.</p>
<p>This static duck type defines methods required to be used by
palace decoders. Despite its name, a <cite>FileIO</cite> is not necessarily
@ -195,7 +196,7 @@ or 2 (move relative to end of file).</p></li>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

11
html/reference/index.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Reference &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Reference &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -15,7 +16,7 @@
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Audio Devices" href="device.html" />
<link rel="prev" title="Play an Audio" href="../tutorial/play-audio.html" />
<link rel="prev" title="Source Manipulation" href="../tutorial/source.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@ -96,7 +97,7 @@
<ul>
<li>
&larr;
<a href="../tutorial/play-audio.html" title="Previous document">Play an Audio</a>
<a href="../tutorial/source.html" title="Previous document">Source Manipulation</a>
</li>
<li>
<a href="device.html" title="Next document">Audio Devices</a>
@ -160,7 +161,7 @@
<ul>
<li>
&larr;
<a href="../tutorial/play-audio.html" title="Previous document">Play an Audio</a>
<a href="../tutorial/source.html" title="Previous document">Source Manipulation</a>
</li>
<li>
<a href="device.html" title="Next document">Audio Devices</a>
@ -178,7 +179,7 @@
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

93
html/reference/source.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Sources &amp; Source Groups &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Sources &amp; Source Groups &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -144,13 +145,14 @@ foggy air and lower values simulating dryer air; default to 0.</p>
<code class="sig-name descname">cone_angles</code><a class="headerlink" href="#palace.Source.cone_angles" title="Permalink to this definition"></a></dt>
<dd><p>Cone inner and outer angles in degrees.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>inner</strong> (<em>float</em>) – The area within which the listener will hear the source
without extra attenuation, default to 360.</p></li>
<li><p><strong>outer</strong> (<em>float</em>) – The area outside of which the listener will hear the source
attenuated according to <cite>outer_cone_gains</cite>, default to 360.</p></li>
</ul>
</p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><strong>ValueError</strong> – If set to a value where <cite>inner</cite> is greater than <cite>outer</cite>
@ -177,8 +179,8 @@ the source is in the inner cone.</p>
distance is clamped to the specified range before applying
distance-related attenuation.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>refdist</strong> (<em>float</em>) – The distance at which the source’s volume will not have
any extra attenuation (an effective gain multiplier of 1),
default to 0.</p></li>
@ -186,6 +188,7 @@ default to 0.</p></li>
maximum value of a single-precision floating-point variable
(2**128 - 2**104).</p></li>
</ul>
</p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><strong>ValueError</strong> – If set to a value where <cite>refdist</cite> is greater than <cite>maxdist</cite>
@ -253,9 +256,16 @@ for the fading to be smooth.</p>
<dt id="palace.Source.gain_auto">
<code class="sig-name descname">gain_auto</code><a class="headerlink" href="#palace.Source.gain_auto" title="Permalink to this definition"></a></dt>
<dd><p>Whether automatically adjust gains.</p>
<p>Respectively for direct path’s high frequency gain,
send paths’ gain and send paths’ high-frequency gain are
automatically adjusted. The default is <cite>True</cite> for all.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>direct_hf</strong> (<em>bool</em>) – Direct path’s high frequency gain, default to <cite>True</cite>.</p></li>
<li><p><strong>send</strong> (<em>bool</em>) – Send paths’ gain, default to <cite>True</cite>.</p></li>
<li><p><strong>send_hf</strong> (<em>bool</em>) – Send paths’ high-frequency, default to <cite>True</cite>.</p></li>
</ul>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py attribute">
@ -265,11 +275,12 @@ automatically adjusted. The default is <cite>True</cite> for all.</p>
<p>This is used after distance and cone attenuation are applied
to the gain base and before the adjustments of the filter gain.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>mingain</strong> (<em>float</em>) – Minimum gain, default to 0.</p></li>
<li><p><strong>maxgain</strong> (<em>float</em>) – Maximum gain, default to 1.</p></li>
</ul>
</p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><strong>ValueError</strong> – If set to a value where <cite>mingain</cite> is greater than <cite>maxgain</cite>
@ -301,16 +312,16 @@ from its current group.</p>
<dt id="palace.Source.latency">
<em class="property">property </em><code class="sig-name descname">latency</code><a class="headerlink" href="#palace.Source.latency" title="Permalink to this definition"></a></dt>
<dd><p>Source latency in nanoseconds.</p>
<p>If the <cite>AL_SOFT_source_latency</cite> extension is unsupported,
the latency will be 0.</p>
<p>If <cite>AL_SOFT_source_latency</cite> extension is unsupported,
this will be 0.</p>
</dd></dl>
<dl class="py method">
<dt id="palace.Source.latency_seconds">
<em class="property">property </em><code class="sig-name descname">latency_seconds</code><a class="headerlink" href="#palace.Source.latency_seconds" title="Permalink to this definition"></a></dt>
<dd><p>Source latency in seconds.</p>
<p>If the <cite>AL_SOFT_source_latency</cite> extension is unsupported,
the latency will be 0.</p>
<p>If <cite>AL_SOFT_source_latency</cite> extension is unsupported,
this will be 0.</p>
</dd></dl>
<dl class="py attribute">
@ -323,15 +334,16 @@ the latency will be 0.</p>
<dl class="py attribute">
<dt id="palace.Source.offset">
<code class="sig-name descname">offset</code><a class="headerlink" href="#palace.Source.offset" title="Permalink to this definition"></a></dt>
<dd><p>Source offset in sample frames. For streaming sources
this will be the offset based on the decoder’s read position.</p>
<dd><p>Source offset in sample frames.</p>
<p>For streaming sources, this will be
based on decoder’s read position.</p>
</dd></dl>
<dl class="py method">
<dt id="palace.Source.offset_seconds">
<em class="property">property </em><code class="sig-name descname">offset_seconds</code><a class="headerlink" href="#palace.Source.offset_seconds" title="Permalink to this definition"></a></dt>
<dd><p>Source offset in seconds.</p>
<p>For streaming sources this will be the offset based on
<p>For streaming sources, this will be based on
the decoder’s read position.</p>
</dd></dl>
@ -340,15 +352,16 @@ the decoder’s read position.</p>
<code class="sig-name descname">orientation</code><a class="headerlink" href="#palace.Source.orientation" title="Permalink to this definition"></a></dt>
<dd><p>3D orientation of the source.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>at</strong> (<em>Tuple</em><em>[</em><em>float</em><em>, </em><em>float</em><em>, </em><em>float</em><em>]</em>) – Relative position.</p></li>
<li><p><strong>up</strong> (<em>Tuple</em><em>[</em><em>float</em><em>, </em><em>float</em><em>, </em><em>float</em><em>]</em>) – Relative direction.</p></li>
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>at</strong> (<em>Tuple[float, float, float]</em>) – Relative position.</p></li>
<li><p><strong>up</strong> (<em>Tuple[float, float, float]</em>) – Relative direction.</p></li>
</ul>
</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>Unlike the <cite>AL_EXT_BFORMAT</cite> extension this property
<p>Unlike <cite>AL_EXT_BFORMAT</cite> extension this property
comes from, this also affects the facing direction.</p>
</dd></dl>
@ -357,13 +370,14 @@ comes from, this also affects the facing direction.</p>
<code class="sig-name descname">outer_cone_gains</code><a class="headerlink" href="#palace.Source.outer_cone_gains" title="Permalink to this definition"></a></dt>
<dd><p>Gain when listener is out of the source’s outer cone area.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>gain</strong> (<em>float</em>) – Linear gain applying to all frequencies, default to 1.</p></li>
<li><p><strong>gain_hf</strong> (<em>float</em>) – Linear gain applying extra attenuation to high frequencies
creating a low-pass effect, default to 1. It has no effect
without the <cite>ALC_EXT_EFX</cite> extension.</p></li>
</ul>
</p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><strong>ValueError</strong> – If either of the gains is set to a value
@ -420,7 +434,7 @@ sources are played.</p>
<dt id="palace.Source.radius">
<code class="sig-name descname">radius</code><a class="headerlink" href="#palace.Source.radius" title="Permalink to this definition"></a></dt>
<dd><p>Radius of the source, as if it is a sound-emitting sphere.</p>
<p>This has no effect without the <cite>AL_EXT_SOURCE_RADIUS</cite> extension.</p>
<p>This has no effect without <cite>AL_EXT_SOURCE_RADIUS</cite> extension.</p>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><strong>ValueError</strong> – If set to a negative value.</p>
@ -454,19 +468,24 @@ without the <cite>AL_SOFT_source_resampler</cite> extension.</p>
<dl class="py attribute">
<dt id="palace.Source.rolloff_factors">
<code class="sig-name descname">rolloff_factors</code><a class="headerlink" href="#palace.Source.rolloff_factors" title="Permalink to this definition"></a></dt>
<dd><p>Rolloff factor and room factor for the direct and send paths.</p>
<dd><p>Rolloff factors for the direct and send paths.</p>
<p>This is effectively a distance scaling relative to
the reference distance.</p>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><strong>ValueError</strong> – If either of rolloff factors is set to a negative value.</p>
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p><ul class="simple">
<li><p><strong>factor</strong> (<em>float</em>) – Rolloff factor.</p></li>
<li><p><strong>room_factor</strong> (<em>float</em>) – Room rolloff factor, default to 0 which disables
distance attenuation for send paths. This is because
the reverb engine will, by default, apply a more realistic
room decay based on the reverb decay time and distance.</p></li>
</ul>
</p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><strong>ValueError</strong> – If either of rolloff factors is set to a negative value.</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>To disable distance attenuation for send paths,
set room factor to 0. The reverb engine will, by default,
apply a more realistic room decay based on the reverb decay
time and distance.</p>
</dd></dl>
<dl class="py method">
@ -493,7 +512,7 @@ features), <cite>False</cite> (never has 3D spatialization features),
or <cite>None</cite> (spatialization is enabled based on playing
a mono sound or not, default).</p>
<p>This has no effect without
the <cite>AL_SOFT_source_spatialize</cite> extension.</p>
<cite>AL_SOFT_source_spatialize</cite> extension.</p>
</dd></dl>
<dl class="py attribute">
@ -503,7 +522,7 @@ the <cite>AL_SOFT_source_spatialize</cite> extension.</p>
<p>The angles go counter-clockwise, with 0 being in front
and positive values going left.</p>
<p>This is only used for stereo playback and has no effect
without the <cite>AL_EXT_STEREO_ANGLES</cite> extension.</p>
without <cite>AL_EXT_STEREO_ANGLES</cite> extension.</p>
</dd></dl>
<dl class="py method">
@ -559,7 +578,7 @@ By default <cite>current_context()</cite> is used.</p>
<dl class="py attribute">
<dt id="palace.SourceGroup.parent_group">
<code class="sig-name descname">parent_group</code><a class="headerlink" href="#palace.SourceGroup.parent_group" title="Permalink to this definition"></a></dt>
<dd><p>The source group this source group is a child of.</p>
<dd><p>The parent source group of this source group.</p>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><strong>RuntimeException</strong> – If this group is being added to its sub-group
@ -639,7 +658,7 @@ By default <cite>current_context()</cite> is used.</p>
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

5
html/search.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Search &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Search &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
@ -124,7 +125,7 @@
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>

2
html/searchindex.js
View File

File diff suppressed because one or more lines are too long

6
html/tutorial/context.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Context Creation &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Context Creation &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -33,6 +34,7 @@
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Tutorial</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Context Creation</a></li>
<li class="toctree-l2"><a class="reference internal" href="play-audio.html">Play an Audio</a></li>
<li class="toctree-l2"><a class="reference internal" href="source.html">Source Manipulation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
@ -164,7 +166,7 @@ in <a class="reference internal" href="../reference/device.html#palace.device_na
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

12
html/tutorial/index.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Tutorial &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Tutorial &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -33,6 +34,7 @@
<li class="toctree-l1 current"><a class="current reference internal" href="#">Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="context.html">Context Creation</a></li>
<li class="toctree-l2"><a class="reference internal" href="play-audio.html">Play an Audio</a></li>
<li class="toctree-l2"><a class="reference internal" href="source.html">Source Manipulation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
@ -119,6 +121,12 @@
<li class="toctree-l2"><a class="reference internal" href="play-audio.html#decode-the-audio-file">Decode the Audio File</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="source.html">Source Manipulation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="source.html#moving-the-source">Moving the Source</a></li>
<li class="toctree-l2"><a class="reference internal" href="source.html#speed-and-pitch">Speed and Pitch</a></li>
<li class="toctree-l2"><a class="reference internal" href="source.html#air-absorption-factor">Air Absorption Factor</a></li>
</ul>
</li>
</ul>
</div>
</div>
@ -149,7 +157,7 @@
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

12
html/tutorial/play-audio.html
View File

@ -4,7 +4,8 @@
<html>
<head>
<meta charset="utf-8" />
<title>Play an Audio &#8212; palace 0.2.0 documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Play an Audio &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
@ -14,7 +15,7 @@
<script src="../_static/language_data.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Reference" href="../reference/index.html" />
<link rel="next" title="Source Manipulation" href="source.html" />
<link rel="prev" title="Context Creation" href="context.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@ -33,6 +34,7 @@
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Tutorial</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="context.html">Context Creation</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Play an Audio</a></li>
<li class="toctree-l2"><a class="reference internal" href="source.html">Source Manipulation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
@ -94,7 +96,7 @@
<a href="context.html" title="Previous document">Context Creation</a>
</li>
<li>
<a href="../reference/index.html" title="Next document">Reference</a>
<a href="source.html" title="Next document">Source Manipulation</a>
&rarr;
</li>
</ul>
@ -198,7 +200,7 @@ is to <code class="docutils literal notranslate"><span class="pre">sleep</span><
<a href="context.html" title="Previous document">Context Creation</a>
</li>
<li>
<a href="../reference/index.html" title="Next document">Reference</a>
<a href="source.html" title="Next document">Source Manipulation</a>
&rarr;
</li>
</ul>
@ -213,7 +215,7 @@ is to <code class="docutils literal notranslate"><span class="pre">sleep</span><
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.0.3</a>
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|

216
html/tutorial/source.html Normal file
View File

@ -0,0 +1,216 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Source Manipulation &#8212; palace 0.2.1 documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Reference" href="../reference/index.html" />
<link rel="prev" title="Play an Audio" href="play-audio.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../installation.html">Installation</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Tutorial</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="context.html">Context Creation</a></li>
<li class="toctree-l2"><a class="reference internal" href="play-audio.html">Play an Audio</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Source Manipulation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../design.html">Design Principles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">Getting Involved</a></li>
<li class="toctree-l1"><a class="reference internal" href="../copying.html">Copying</a></li>
</ul>
<h3>Quick Navigation</h3>
<ul>
<li class="toctree-l1">
<a class="reference external" href="https://pypi.org/project/palace/">
Python Package Index
</a>
</li>
<li class="toctree-l1">
<a class="reference external"
href="https://travis-ci.com/github/McSinyx/palace">
Travis CI Build
</a>
</li>
<li class="toctree-l1">
<a class="reference external"
href="https://ci.appveyor.com/project/McSinyx/palace">
AppVeyor Build
</a>
</li>
<li class="toctree-l1">
<a class="reference external" href="https://github.com/McSinyx/palace">
GitHub Repository
</a>
</li>
<li class="toctree-l1">
<a class="reference external"
href="https://matrix.to/#/#palace-dev:matrix.org">
Matrix Chat Room
</a>
</li>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="related top">
&nbsp;
<nav id="rellinks">
<ul>
<li>
&larr;
<a href="play-audio.html" title="Previous document">Play an Audio</a>
</li>
<li>
<a href="../reference/index.html" title="Next document">Reference</a>
&rarr;
</li>
</ul>
</nav>
</div>
<div class="body" role="main">
<div class="section" id="source-manipulation">
<h1>Source Manipulation<a class="headerlink" href="#source-manipulation" title="Permalink to this headline"></a></h1>
<p>We have created a source in the last section.
As said previously, its properties can be manipulated to create wanted effects.</p>
<div class="section" id="moving-the-source">
<h2>Moving the Source<a class="headerlink" href="#moving-the-source" title="Permalink to this headline"></a></h2>
<p>Changing <a class="reference internal" href="../reference/source.html#palace.Source.position" title="palace.Source.position"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Source.position</span></code></a> is one of the most noticeable,
but first, we have to enable spatialization via <a class="reference internal" href="../reference/source.html#palace.Source.spatialize" title="palace.Source.spatialize"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Source.spatialize</span></code></a>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">time</span> <span class="kn">import</span> <span class="n">sleep</span>
<span class="kn">from</span> <span class="nn">palace</span> <span class="kn">import</span> <span class="n">Device</span><span class="p">,</span> <span class="n">Context</span><span class="p">,</span> <span class="n">Source</span><span class="p">,</span> <span class="n">decode</span>
<span class="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">device</span><span class="p">,</span> <span class="n">Context</span><span class="p">(</span><span class="n">device</span><span class="p">)</span> <span class="k">as</span> <span class="n">context</span><span class="p">,</span> <span class="n">Source</span><span class="p">()</span> <span class="k">as</span> <span class="n">source</span><span class="p">:</span>
<span class="n">source</span><span class="o">.</span><span class="n">spatialize</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">decoder</span> <span class="o">=</span> <span class="n">decode</span><span class="p">(</span><span class="s1">&#39;some_audio.ogg&#39;</span><span class="p">)</span>
<span class="n">decoder</span><span class="o">.</span><span class="n">play</span><span class="p">(</span><span class="mi">12000</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="n">source</span><span class="p">)</span>
<span class="k">while</span> <span class="n">source</span><span class="o">.</span><span class="n">playing</span><span class="p">:</span>
<span class="n">sleep</span><span class="p">(</span><span class="mf">0.025</span><span class="p">)</span>
<span class="n">context</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
</pre></div>
</div>
<p>Now, we can set the position of the source in this virtual 3D space.
The position is a 3-tuple indicating the coordinate of the source.
The axes are aligned according to the normal coordinate system:</p>
<ul class="simple">
<li><p>The x-axis goes from left to right</p></li>
<li><p>The y-axis goes from below to above</p></li>
<li><p>The z-axis goes from front to back</p></li>
</ul>
<p>For example, this will set the source above the listener:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For this too work for stereo, you have to have HRTF enabled.
You can check that via <a class="reference internal" href="../reference/device.html#palace.Device.current_hrtf" title="palace.Device.current_hrtf"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Device.current_hrtf</span></code></a>.</p>
</div>
<p>You can as well use a function to move the source automatically by writing
a function that generate positions. A simple example is circular motion.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">itertools</span> <span class="kn">import</span> <span class="n">takewhile</span><span class="p">,</span> <span class="n">count</span>
<span class="o">...</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">takewhile</span><span class="p">(</span><span class="n">src</span><span class="o">.</span><span class="n">playing</span><span class="p">,</span> <span class="n">count</span><span class="p">(</span><span class="n">step</span><span class="o">=</span><span class="mf">0.025</span><span class="p">)):</span>
<span class="n">source</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="n">sin</span><span class="p">(</span><span class="n">i</span><span class="p">),</span> <span class="mi">0</span><span class="p">,</span> <span class="n">cos</span><span class="p">(</span><span class="o">-</span><span class="n">i</span><span class="p">)</span>
<span class="o">...</span>
</pre></div>
</div>
<p>A more well-written example of this can be found <a class="reference external" href="https://github.com/McSinyx/palace/blob/master/examples/palace-hrtf.py">in our repository</a>.</p>
</div>
<div class="section" id="speed-and-pitch">
<h2>Speed and Pitch<a class="headerlink" href="#speed-and-pitch" title="Permalink to this headline"></a></h2>
<p>Modifying <code class="xref py py-attr docutils literal notranslate"><span class="pre">pitch</span></code> changes the playing speed, effectively changing
pitch. Pitch can be any positive number.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">src</span><span class="o">.</span><span class="n">pitch</span> <span class="o">=</span> <span class="mi">2</span> <span class="c1"># high pitch</span>
<span class="n">src</span><span class="o">.</span><span class="n">pitch</span> <span class="o">=</span> <span class="mf">0.4</span> <span class="c1"># low pitch</span>
</pre></div>
</div>
</div>
<div class="section" id="air-absorption-factor">
<h2>Air Absorption Factor<a class="headerlink" href="#air-absorption-factor" title="Permalink to this headline"></a></h2>
<p><a class="reference internal" href="../reference/source.html#palace.Source.air_absorption_factor" title="palace.Source.air_absorption_factor"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Source.air_absorption_factor</span></code></a> simulates atmospheric high-frequency
air absorption. Higher values simulate foggy air and lower values simulate
drier air.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">src</span><span class="o">.</span><span class="n">air_absorption_factor</span> <span class="o">=</span> <span class="mi">9</span> <span class="c1"># very high humidity</span>
<span class="n">src</span><span class="o">.</span><span class="n">air_absorption_factor</span> <span class="o">=</span> <span class="mi">0</span> <span class="c1"># dry air (default)</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="related bottom">
&nbsp;
<nav id="rellinks">
<ul>
<li>
&larr;
<a href="play-audio.html" title="Previous document">Play an Audio</a>
</li>
<li>
<a href="../reference/index.html" title="Next document">Reference</a>
&rarr;
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2019, 2020 Nguyễn Gia Phong et al.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 3.2.1</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/tutorial/source.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

2
requirements.txt
View File

@ -1,2 +1,2 @@
palace
sphinx >= 3.*
sphinx >= 3.2

2
src/conf.py
View File

@ -22,7 +22,7 @@ copyright = '2019, 2020 Nguyễn Gia Phong et al'
author = 'Nguyễn Gia Phong et al.'
# The full version, including alpha/beta/rc tags
release = '0.2.0'
release = '0.2.1'
# -- General configuration ---------------------------------------------------

2
src/index.rst
View File

@ -7,7 +7,7 @@ for audio rendering using OpenAL:
* 3D positional rendering, with HRTF_ support for stereo systems
* Environmental effects: reverb, atmospheric air absorption,
sound occlusion and obstruction
* Out-of-the-box codec support:
* Out-of-the-box codec support: FLAC, MP3, Ogg Vorbis, Opus, WAV, AIFF, etc.
Palace wraps around the C++ interface alure_ using Cython_ for a safe and
convenient interface with type hinting, data descriptors and context managers,

2
src/tutorial/index.rst
View File

@ -8,8 +8,8 @@ This tutorial will guide you on:
context
play-audio
source
.. comment these to add later
Moving sources
Adding effects
Customize decoder
Generate sounds

82
src/tutorial/source.rst Normal file
View File

@ -0,0 +1,82 @@
Source Manipulation
===================
.. currentmodule:: palace
We have created a source in the last section.
As said previously, its properties can be manipulated to create wanted effects.
Moving the Source
-----------------
Changing :py:attr:`Source.position` is one of the most noticeable,
but first, we have to enable spatialization via :py:attr:`Source.spatialize`.
.. code-block:: python
from time import sleep
from palace import Device, Context, Source, decode
with Device() as device, Context(device) as context, Source() as source:
source.spatialize = True
decoder = decode('some_audio.ogg')
decoder.play(12000, 4, source)
while source.playing:
sleep(0.025)
context.update()
Now, we can set the position of the source in this virtual 3D space.
The position is a 3-tuple indicating the coordinate of the source.
The axes are aligned according to the normal coordinate system:
- The x-axis goes from left to right
- The y-axis goes from below to above
- The z-axis goes from front to back
For example, this will set the source above the listener::
src.position = 0, 1, 0
.. note::
For this too work for stereo, you have to have HRTF enabled.
You can check that via :py:attr:`Device.current_hrtf`.
You can as well use a function to move the source automatically by writing
a function that generate positions. A simple example is circular motion.
.. code-block:: python
from itertools import takewhile, count
...
for i in takewhile(src.playing, count(step=0.025)):
source.position = sin(i), 0, cos(-i)
...
A more well-written example of this can be found `in our repository`_.
Speed and Pitch
---------------
Modifying :py:attr:`pitch` changes the playing speed, effectively changing
pitch. Pitch can be any positive number.
.. code-block:: python
src.pitch = 2 # high pitch
src.pitch = 0.4 # low pitch
Air Absorption Factor
---------------------
:py:attr:`Source.air_absorption_factor` simulates atmospheric high-frequency
air absorption. Higher values simulate foggy air and lower values simulate
drier air.
.. code-block:: python
src.air_absorption_factor = 9 # very high humidity
src.air_absorption_factor = 0 # dry air (default)
.. _in our repository:
https://github.com/McSinyx/palace/blob/master/examples/palace-hrtf.py