deploy: 708f23b35a

2020-10-06 13:42:47 +00:00 · 2020-10-06 13:42:47 +00:00 · 110db969c2
parent f6c07be6b6
commit 110db969c2
11 changed files with 365 additions and 6 deletions
--- a/_sources/tutorial/effect.rst.txt
+++ b/_sources/tutorial/effect.rst.txt
@ -0,0 +1,65 @@
+Adding an Effect
+================
+
+.. currentmodule:: palace
+
+This section will focus on how to add effects to the audio.
+
+There are two set of audio effects supported by palace: :py:class:`ReverbEffect`
+and :py:class:`ChorusEffect`.
+
+Reverb Effect
+-------------
+
+Reverb happens when a sound is reflected and then decay as the sound is absorbed
+by the objects in the medium.  :py:class:`ReverbEffect` facilitates such effect.
+
+Creating a reverb effect can be as simple as:
+
+.. code-block:: python
+
+   with ReverbEffect() as effect:
+       source.sends[0].effect = effect
+
+:py:attr:`Source.sends` is a collection of send path signals, each of which
+contains `effects` and `filter` that describes it.  Here we are only concerned
+about the former.
+
+The above code would yield a *generic* reverb effect by default.
+There are several other presets that you can use, which are listed
+by :py:data:`reverb_preset_names`.  To use these preset, you can simply provide
+the preset effect name as the first parameter for the constructor.  For example,
+to use `PIPE_LARGE` preset effect, you can initialize the effect like below:
+
+.. code-block:: python
+
+   with ReverbEffect('PIPE_LARGE') as effect:
+       source.sends[0].effect = effect
+
+These effects can be modified via their attributes.
+
+.. code-block:: python
+
+   effect.gain = 0.4
+   effect.diffusion = 0.65
+   late_reverb_pan = 0.2, 0.1, 0.3
+
+The list of these attributes and their constraints can be found
+in the documentation of :py:class:`ReverbEffect`.
+
+Chorus Effect
+-------------
+
+:py:class:`ChorusEffect` does not have preset effects like
+:py:class:`ReverbEffect`, so you would have to initialize the effect attributes
+on creation.
+
+There are five parameters to initialize the effect, respectively: waveform,
+phase, depth, feedback, and delay.
+
+.. code-block:: python
+
+   with ChorusEffect('sine', 20, 0.4, 0.5, 0.008) as effect:
+       source.sends[0].effect = effect
+
+For the constraints of these parameters, please refer to the documentation.
--- a/_sources/tutorial/index.rst.txt
+++ b/_sources/tutorial/index.rst.txt
@ -9,7 +9,7 @@ This tutorial will guide you on:
   context
   play-audio
   source
+   effect
 .. comment these to add later
-   Adding effects
   Customize decoder
   Generate sounds
--- a/index.html
+++ b/index.html
@ -188,6 +188,7 @@ following <span class="target" id="index-0"></span><a class="pep reference exter
 <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>
+<li class="toctree-l2"><a class="reference internal" href="tutorial/effect.html">Adding an Effect</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="reference/index.html">Reference</a><ul>
--- a/objects.inv
+++ b/objects.inv
--- a/reference/index.html
+++ b/reference/index.html
@ -37,7 +37,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="Source Manipulation" href="../tutorial/source.html" /> 
+    <link rel="prev" title="Adding an Effect" href="../tutorial/effect.html" /> 
 </head>

 <body class="wy-body-for-nav">
@ -226,7 +226,7 @@
        <a href="device.html" class="btn btn-neutral float-right" title="Audio Devices" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
-        <a href="../tutorial/source.html" class="btn btn-neutral float-left" title="Source Manipulation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+        <a href="../tutorial/effect.html" class="btn btn-neutral float-left" title="Adding an Effect" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  
--- a/searchindex.js
+++ b/searchindex.js
--- a/tutorial/context.html
+++ b/tutorial/context.html
@ -93,6 +93,7 @@
 </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>
+<li class="toctree-l2"><a class="reference internal" href="effect.html">Adding an Effect</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
--- a/tutorial/effect.html
+++ b/tutorial/effect.html
@ -0,0 +1,284 @@
+
+
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8">
+  
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  
+  <title>Adding an Effect &mdash; palace 0.2.1 documentation</title>
+  
+
+  
+  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
+  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+  
+  
+  
+  
+
+  
+  <!--[if lt IE 9]>
+    <script src="../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+  
+    
+      <script type="text/javascript" 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>
+    
+    <script type="text/javascript" src="../_static/js/theme.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="Source Manipulation" href="source.html" /> 
+</head>
+
+<body class="wy-body-for-nav">
+
+   
+  <div class="wy-grid-for-nav">
+    
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+          
+
+          
+            <a href="../index.html" class="icon icon-home" alt="Documentation Home"> palace
+          
+
+          
+          </a>
+
+          
+            
+            
+          
+
+          
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+
+          
+        </div>
+
+        
+        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+          
+            
+            
+              
+            
+            
+              <p class="caption"><span class="caption-text">Table of Contents</span></p>
+<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"><a class="reference internal" href="source.html">Source Manipulation</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Adding an Effect</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#reverb-effect">Reverb Effect</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#chorus-effect">Chorus Effect</a></li>
+</ul>
+</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>
+<p class="caption"><span class="caption-text">Quick Navigation</span></p>
+<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>
+        
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+
+      
+      <nav class="wy-nav-top" aria-label="top navigation">
+        
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../index.html">palace</a>
+        
+      </nav>
+
+
+      <div class="wy-nav-content">
+        
+        <div class="rst-content">
+        
+          
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<div role="navigation" aria-label="breadcrumbs navigation">
+
+  <ul class="wy-breadcrumbs">
+    
+      <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
+        
+          <li><a href="index.html">Tutorial</a> &raquo;</li>
+        
+      <li>Adding an Effect</li>
+    
+    
+      <li class="wy-breadcrumbs-aside">
+        
+            
+            <a href="../_sources/tutorial/effect.rst.txt" rel="nofollow"> View page source</a>
+          
+        
+      </li>
+    
+  </ul>
+
+  
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+            
+  <div class="section" id="adding-an-effect">
+<h1>Adding an Effect<a class="headerlink" href="#adding-an-effect" title="Permalink to this headline">¶</a></h1>
+<p>This section will focus on how to add effects to the audio.</p>
+<p>There are two set of audio effects supported by palace: <a class="reference internal" href="../reference/effect.html#palace.ReverbEffect" title="palace.ReverbEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReverbEffect</span></code></a>
+and <a class="reference internal" href="../reference/effect.html#palace.ChorusEffect" title="palace.ChorusEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ChorusEffect</span></code></a>.</p>
+<div class="section" id="reverb-effect">
+<h2>Reverb Effect<a class="headerlink" href="#reverb-effect" title="Permalink to this headline">¶</a></h2>
+<p>Reverb happens when a sound is reflected and then decay as the sound is absorbed
+by the objects in the medium.  <a class="reference internal" href="../reference/effect.html#palace.ReverbEffect" title="palace.ReverbEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReverbEffect</span></code></a> facilitates such effect.</p>
+<p>Creating a reverb effect can be as simple as:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ReverbEffect</span><span class="p">()</span> <span class="k">as</span> <span class="n">effect</span><span class="p">:</span>
+    <span class="n">source</span><span class="o">.</span><span class="n">sends</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">effect</span> <span class="o">=</span> <span class="n">effect</span>
+</pre></div>
+</div>
+<p><a class="reference internal" href="../reference/source.html#palace.Source.sends" title="palace.Source.sends"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Source.sends</span></code></a> is a collection of send path signals, each of which
+contains <code class="xref py py-obj docutils literal notranslate"><span class="pre">effects</span></code> and <code class="xref py py-obj docutils literal notranslate"><span class="pre">filter</span></code> that describes it.  Here we are only concerned
+about the former.</p>
+<p>The above code would yield a <em>generic</em> reverb effect by default.
+There are several other presets that you can use, which are listed
+by <a class="reference internal" href="../reference/effect.html#palace.reverb_preset_names" title="palace.reverb_preset_names"><code class="xref py py-data docutils literal notranslate"><span class="pre">reverb_preset_names</span></code></a>.  To use these preset, you can simply provide
+the preset effect name as the first parameter for the constructor.  For example,
+to use <code class="xref py py-obj docutils literal notranslate"><span class="pre">PIPE_LARGE</span></code> preset effect, you can initialize the effect like below:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ReverbEffect</span><span class="p">(</span><span class="s1">&#39;PIPE_LARGE&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">effect</span><span class="p">:</span>
+    <span class="n">source</span><span class="o">.</span><span class="n">sends</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">effect</span> <span class="o">=</span> <span class="n">effect</span>
+</pre></div>
+</div>
+<p>These effects can be modified via their attributes.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">effect</span><span class="o">.</span><span class="n">gain</span> <span class="o">=</span> <span class="mf">0.4</span>
+<span class="n">effect</span><span class="o">.</span><span class="n">diffusion</span> <span class="o">=</span> <span class="mf">0.65</span>
+<span class="n">late_reverb_pan</span> <span class="o">=</span> <span class="mf">0.2</span><span class="p">,</span> <span class="mf">0.1</span><span class="p">,</span> <span class="mf">0.3</span>
+</pre></div>
+</div>
+<p>The list of these attributes and their constraints can be found
+in the documentation of <a class="reference internal" href="../reference/effect.html#palace.ReverbEffect" title="palace.ReverbEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReverbEffect</span></code></a>.</p>
+</div>
+<div class="section" id="chorus-effect">
+<h2>Chorus Effect<a class="headerlink" href="#chorus-effect" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="../reference/effect.html#palace.ChorusEffect" title="palace.ChorusEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ChorusEffect</span></code></a> does not have preset effects like
+<a class="reference internal" href="../reference/effect.html#palace.ReverbEffect" title="palace.ReverbEffect"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReverbEffect</span></code></a>, so you would have to initialize the effect attributes
+on creation.</p>
+<p>There are five parameters to initialize the effect, respectively: waveform,
+phase, depth, feedback, and delay.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">ChorusEffect</span><span class="p">(</span><span class="s1">&#39;sine&#39;</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mf">0.4</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">,</span> <span class="mf">0.008</span><span class="p">)</span> <span class="k">as</span> <span class="n">effect</span><span class="p">:</span>
+    <span class="n">source</span><span class="o">.</span><span class="n">sends</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">effect</span> <span class="o">=</span> <span class="n">effect</span>
+</pre></div>
+</div>
+<p>For the constraints of these parameters, please refer to the documentation.</p>
+</div>
+</div>
+
+
+           </div>
+           
+          </div>
+          <footer>
+  
+    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
+      
+        <a href="../reference/index.html" class="btn btn-neutral float-right" title="Reference" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
+      
+      
+        <a href="source.html" class="btn btn-neutral float-left" title="Source Manipulation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+      
+    </div>
+  
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>
+        
+        &copy; Copyright 2019, 2020  Nguyễn Gia Phong et al
+
+    </p>
+  </div>
+    
+    
+    
+    Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a
+    
+    <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a>
+    
+    provided by <a href="https://readthedocs.org">Read the Docs</a>. 
+
+</footer>
+
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+  
+
+  <script type="text/javascript">
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script>
+
+  
+  
+    
+   
+
+</body>
+</html>
--- a/tutorial/index.html
+++ b/tutorial/index.html
@ -89,6 +89,7 @@
 <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>
+<li class="toctree-l2"><a class="reference internal" href="effect.html">Adding an Effect</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
@ -189,6 +190,11 @@
 <li class="toctree-l2"><a class="reference internal" href="source.html#air-absorption-factor">Air Absorption Factor</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="effect.html">Adding an Effect</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="effect.html#reverb-effect">Reverb Effect</a></li>
+<li class="toctree-l2"><a class="reference internal" href="effect.html#chorus-effect">Chorus Effect</a></li>
+</ul>
+</li>
 </ul>
 </div>
 </div>
--- a/tutorial/play-audio.html
+++ b/tutorial/play-audio.html
@ -93,6 +93,7 @@
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="source.html">Source Manipulation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="effect.html">Adding an Effect</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
--- a/tutorial/source.html
+++ b/tutorial/source.html
@ -36,7 +36,7 @@
    
    <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="Adding an Effect" href="effect.html" />
    <link rel="prev" title="Play an Audio" href="play-audio.html" /> 
 </head>

@ -94,6 +94,7 @@
 <li class="toctree-l3"><a class="reference internal" href="#air-absorption-factor">Air Absorption Factor</a></li>
 </ul>
 </li>
+<li class="toctree-l2"><a class="reference internal" href="effect.html">Adding an Effect</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference</a></li>
@ -252,7 +253,7 @@ drier air.</p>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
-        <a href="../reference/index.html" class="btn btn-neutral float-right" title="Reference" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
+        <a href="effect.html" class="btn btn-neutral float-right" title="Adding an Effect" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="play-audio.html" class="btn btn-neutral float-left" title="Play an Audio" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>