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

Writing first two sections of tutorial

This commit is contained in:
Huy Ngo 2020-05-15 17:28:20 +07:00 committed by Nguyễn Gia Phong
parent 4caaee5727
commit fa513ea096
29 changed files with 1055 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doctrees/environment.pickle
View File

Binary file not shown.

BIN
doctrees/index.doctree
View File

Binary file not shown.

BIN
doctrees/tutorial.doctree Normal file
View File

Binary file not shown.

BIN
doctrees/tutorial/context.doctree Normal file
View File

Binary file not shown.

BIN
doctrees/tutorial/index.doctree Normal file
View File

Binary file not shown.

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

Binary file not shown.

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

@ -12,6 +12,7 @@ for a safe, convenient and pleasurable experience.
:maxdepth: 2
installation
tutorial/index
reference
design
contributing

16
html/_sources/tutorial.rst.txt Normal file
View File

@ -0,0 +1,16 @@
Tutorial
========
This tutorial will guide you on:
.. toctree::
:maxdepth: 1
tutorial/context
tutorial/play-audio
.. comment these to add later
Moving sources
Adding effects
Customize decoder
Generate sounds
..

41
html/_sources/tutorial/context.rst.txt Normal file
View File

@ -0,0 +1,41 @@
.. py:currentmodule:: palace
Context Creation
================
A context is an object that allows palace to access OpenAL,
which is essential when you work with palace. Context maintains
the audio environment and contains environment settings and components
such as sources, buffers, and effects.
Creating a Device Object
------------------------
To create a context, we must first create a device,
since it's a parameter of the context object.
To create an object, well, you just have to instantiate
the :py:class:`Device` class.
.. code-block:: python
from palace import Device
with Device() as dev:
# Your code goes here
This is how you declare a :py:class:`Device` object with the default device.
There can be several devices available, which can be found
in :py:data:`device_names`.
Creating a Context
------------------
Now that we've created a device, we can create the context:
.. code-block:: python
from palace import Device, Context
with Device() as dev, Context(dev) as ctx:
# Your code goes here

15
html/_sources/tutorial/index.rst.txt Normal file
View File

@ -0,0 +1,15 @@
Tutorial
========
This tutorial will guide you on:
.. toctree::
:maxdepth: 2
context
play-audio
.. comment these to add later
Moving sources
Adding effects
Customize decoder
Generate sounds

101
html/_sources/tutorial/play-audio.rst.txt Normal file
View File

@ -0,0 +1,101 @@
.. py:currentmodule:: palace
Play an Audio
=============
Now that you know how to create a context,
let's get into the most essential use case: playing audio.
Creating a Source
-----------------
To play an audio, you have to create a source. This source
is an imaginary sound broadcaster, whose positions and properties
can be changed to create desired effects.
.. code-block:: python
from palace import Device, Context, Source
with Device() as dev, Context(dev) as ctx:
with Source() as src:
# to be written
Just like for the case of :py:class:`Context`, :py:class:`Source` creation
requires a context, but here the context is passed implicitly.
Decode the Audio File
---------------------
Palace has a module level function :py:func:`decode`, which decodes audio file
automatically, and this decoded file is a :py:class:`Decoder` object. This object
can be played by a simple :py:meth:`Decoder.play` method.
.. code-block:: python
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
We are almost there. Now, let's look at the document for :py:meth:`Decoder.play`.
The method takes 3 parameters: ``chunk_len``, ``queue_size``, and ``source``.
The source object is optional, because if you don't have it, a new source
will be generated by default.
The audio is divided into chunks, each of which is of length ``chunk_len``.
Then ``queue_size`` is the number of these chunks that it will play.
.. TODO: I think it's better to include a diagram here. Add later
.. code-block:: python
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
dec.play(12000, 4, src)
But we don't want it to play only a small part of the audio. We want it to
play all of it. How do we do that? The answer is a loop.
There is a method, :py:meth:`Context.update`, which update the context and the source.
When the source is updated, it will be filled with new chunks of data from
the decoder.
.. code-block:: python
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
dec.play(12000, 4, src)
while src.playing:
ctx.update()
If you tried this code for a song, you will find that it's a bit rush.
That is because the source is renewed too fast. So, a simple solution
is to ``sleep`` for a while.
.. code-block:: python
from time import sleep
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
dec.play(12000, 4, src)
while src.playing:
sleep(0.025)
ctx.update()
Congratulation! Enjoy your music before we get to the next part of this tutorial.

1
html/contributing.html
View File

@ -30,6 +30,7 @@
<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"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Getting Involved</a><ul>

1
html/copying.html
View File

@ -29,6 +29,7 @@
<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"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.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>

1
html/design.html
View File

@ -30,6 +30,7 @@
<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"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Design Principles</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#the-impl-idiom">The Impl Idiom</a></li>

1
html/genindex.html
View File

@ -29,6 +29,7 @@
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.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>

6
html/index.html
View File

@ -29,6 +29,7 @@
<h3><a href="#">Table of Contents</a></h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.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>
@ -104,6 +105,11 @@ for a safe, convenient and pleasurable experience.</p>
<li class="toctree-l2"><a class="reference internal" href="installation.html#from-source">From source</a></li>
</ul>
</li>
<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>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="reference.html#audio-devices">Audio Devices</a></li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#audio-library-contexts">Audio Library Contexts</a></li>

7
html/installation.html
View File

@ -14,7 +14,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.html" />
<link rel="next" title="Tutorial" href="tutorial/index.html" />
<link rel="prev" title="Welcome to our palace!" href="index.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
@ -35,6 +35,7 @@
<li class="toctree-l2"><a class="reference internal" href="#from-source">From source</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.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>
@ -88,7 +89,7 @@
<a href="index.html" title="Previous document">Welcome to our palace!</a>
</li>
<li>
<a href="reference.html" title="Next document">Reference</a>
<a href="tutorial/index.html" title="Next document">Tutorial</a>
&rarr;
</li>
</ul>
@ -139,7 +140,7 @@ Palace can then be compiled and installed by running:</p>
<a href="index.html" title="Previous document">Welcome to our palace!</a>
</li>
<li>
<a href="reference.html" title="Next document">Reference</a>
<a href="tutorial/index.html" title="Next document">Tutorial</a>
&rarr;
</li>
</ul>

BIN
html/objects.inv
View File

Binary file not shown.

7
html/reference.html
View File

@ -15,7 +15,7 @@
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Design Principles" href="design.html" />
<link rel="prev" title="Installation" href="installation.html" />
<link rel="prev" title="Play an audio" href="tutorial/play-audio.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
@ -30,6 +30,7 @@
<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"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#audio-devices">Audio Devices</a></li>
<li class="toctree-l2"><a class="reference internal" href="#audio-library-contexts">Audio Library Contexts</a></li>
@ -89,7 +90,7 @@
<ul>
<li>
&larr;
<a href="installation.html" title="Previous document">Installation</a>
<a href="tutorial/play-audio.html" title="Previous document">Play an audio</a>
</li>
<li>
<a href="design.html" title="Next document">Design Principles</a>
@ -1982,7 +1983,7 @@ or 2 (move relative to end of file).</p></li>
<ul>
<li>
&larr;
<a href="installation.html" title="Previous document">Installation</a>
<a href="tutorial/play-audio.html" title="Previous document">Play an audio</a>
</li>
<li>
<a href="design.html" title="Next document">Design Principles</a>

1
html/search.html
View File

@ -33,6 +33,7 @@
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.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>

2
html/searchindex.js
View File

File diff suppressed because one or more lines are too long

150
html/tutorial.html Normal file
View File

@ -0,0 +1,150 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Tutorial &#8212; palace 0.2.0 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="Context creation" href="tutorial/context.html" />
<link rel="prev" title="Installation" href="installation.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="current reference internal" href="#">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>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="reference.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>
</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="installation.html" title="Previous document">Installation</a>
</li>
<li>
<a href="tutorial/context.html" title="Next document">Context creation</a>
&rarr;
</li>
</ul>
</nav>
</div>
<div class="body" role="main">
<div class="section" id="tutorial">
<h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline"></a></h1>
<p>This tutorial will guide you on:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial/context.html">Context creation</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial/play-audio.html">Play an audio</a></li>
</ul>
</div>
</div>
</div>
<div class="related bottom">
&nbsp;
<nav id="rellinks">
<ul>
<li>
&larr;
<a href="installation.html" title="Previous document">Installation</a>
</li>
<li>
<a href="tutorial/context.html" title="Next document">Context creation</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.0.3</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="_sources/tutorial.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

173
html/tutorial/context.html Normal file
View File

@ -0,0 +1,173 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Context Creation &#8212; palace 0.2.0 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="Play an Audio" href="play-audio.html" />
<link rel="prev" title="Tutorial" href="index.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 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>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference.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>
</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="index.html" title="Previous document">Tutorial</a>
</li>
<li>
<a href="play-audio.html" title="Next document">Play an Audio</a>
&rarr;
</li>
</ul>
</nav>
</div>
<div class="body" role="main">
<div class="section" id="context-creation">
<h1>Context Creation<a class="headerlink" href="#context-creation" title="Permalink to this headline"></a></h1>
<p>A context is an object that allows palace to access OpenAL,
which is essential when you work with palace. Context maintains
the audio environment and contains environment settings and components
such as sources, buffers, and effects.</p>
<div class="section" id="creating-a-device-object">
<h2>Creating a Device Object<a class="headerlink" href="#creating-a-device-object" title="Permalink to this headline"></a></h2>
<p>To create a context, we must first create a device,
since it’s a parameter of the context object.</p>
<p>To create an object, well, you just have to instantiate
the <a class="reference internal" href="../reference.html#palace.Device" title="palace.Device"><code class="xref py py-class docutils literal notranslate"><span class="pre">Device</span></code></a> class.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">palace</span> <span class="kn">import</span> <span class="n">Device</span>
<span class="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">dev</span><span class="p">:</span>
<span class="c1"># Your code goes here</span>
</pre></div>
</div>
<p>This is how you declare a <a class="reference internal" href="../reference.html#palace.Device" title="palace.Device"><code class="xref py py-class docutils literal notranslate"><span class="pre">Device</span></code></a> object with the default device.
There can be several devices available, which can be found
in <a class="reference internal" href="../reference.html#palace.device_names" title="palace.device_names"><code class="xref py py-data docutils literal notranslate"><span class="pre">device_names</span></code></a>.</p>
</div>
<div class="section" id="creating-a-context">
<h2>Creating a Context<a class="headerlink" href="#creating-a-context" title="Permalink to this headline"></a></h2>
<p>Now that we’ve created a device, we can create the context:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></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="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">dev</span><span class="p">,</span> <span class="n">Context</span><span class="p">(</span><span class="n">dev</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="c1"># Your code goes here</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="related bottom">
&nbsp;
<nav id="rellinks">
<ul>
<li>
&larr;
<a href="index.html" title="Previous document">Tutorial</a>
</li>
<li>
<a href="play-audio.html" title="Next document">Play an Audio</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.0.3</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/tutorial/context.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

158
html/tutorial/index.html Normal file
View File

@ -0,0 +1,158 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Tutorial &#8212; palace 0.2.0 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="Context Creation" href="context.html" />
<link rel="prev" title="Installation" href="../installation.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="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>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference.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>
</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="../installation.html" title="Previous document">Installation</a>
</li>
<li>
<a href="context.html" title="Next document">Context Creation</a>
&rarr;
</li>
</ul>
</nav>
</div>
<div class="body" role="main">
<div class="section" id="tutorial">
<h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline"></a></h1>
<p>This tutorial will guide you on:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="context.html">Context Creation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="context.html#creating-a-device-object">Creating a Device Object</a></li>
<li class="toctree-l2"><a class="reference internal" href="context.html#creating-a-context">Creating a Context</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="play-audio.html">Play an Audio</a><ul>
<li class="toctree-l2"><a class="reference internal" href="play-audio.html#creating-a-source">Creating a Source</a></li>
<li class="toctree-l2"><a class="reference internal" href="play-audio.html#decode-the-audio-file">Decode the Audio File</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="related bottom">
&nbsp;
<nav id="rellinks">
<ul>
<li>
&larr;
<a href="../installation.html" title="Previous document">Installation</a>
</li>
<li>
<a href="context.html" title="Next document">Context Creation</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.0.3</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/tutorial/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

222
html/tutorial/play-audio.html Normal file
View File

@ -0,0 +1,222 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Play an Audio &#8212; palace 0.2.0 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.html" />
<link rel="prev" title="Context Creation" href="context.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 current"><a class="current reference internal" href="#">Play an Audio</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../reference.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>
</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="context.html" title="Previous document">Context Creation</a>
</li>
<li>
<a href="../reference.html" title="Next document">Reference</a>
&rarr;
</li>
</ul>
</nav>
</div>
<div class="body" role="main">
<div class="section" id="play-an-audio">
<h1>Play an Audio<a class="headerlink" href="#play-an-audio" title="Permalink to this headline"></a></h1>
<p>Now that you know how to create a context,
let’s get into the most essential use case: playing audio.</p>
<div class="section" id="creating-a-source">
<h2>Creating a Source<a class="headerlink" href="#creating-a-source" title="Permalink to this headline"></a></h2>
<p>To play an audio, you have to create a source. This source
is an imaginary sound broadcaster, whose positions and properties
can be changed to create desired effects.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></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="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">dev</span><span class="p">,</span> <span class="n">Context</span><span class="p">(</span><span class="n">dev</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Source</span><span class="p">()</span> <span class="k">as</span> <span class="n">src</span><span class="p">:</span>
<span class="c1"># to be written</span>
</pre></div>
</div>
<p>Just like for the case of <a class="reference internal" href="../reference.html#palace.Context" title="palace.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a>, <a class="reference internal" href="../reference.html#palace.Source" title="palace.Source"><code class="xref py py-class docutils literal notranslate"><span class="pre">Source</span></code></a> creation
requires a context, but here the context is passed implicitly.</p>
</div>
<div class="section" id="decode-the-audio-file">
<h2>Decode the Audio File<a class="headerlink" href="#decode-the-audio-file" title="Permalink to this headline"></a></h2>
<p>Palace has a module level function <a class="reference internal" href="../reference.html#palace.decode" title="palace.decode"><code class="xref py py-func docutils literal notranslate"><span class="pre">decode()</span></code></a>, which decodes audio file
automatically, and this decoded file is a <a class="reference internal" href="../reference.html#palace.Decoder" title="palace.Decoder"><code class="xref py py-class docutils literal notranslate"><span class="pre">Decoder</span></code></a> object. This object
can be played by a simple <a class="reference internal" href="../reference.html#palace.Decoder.play" title="palace.Decoder.play"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Decoder.play()</span></code></a> method.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></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="n">filename</span> <span class="o">=</span> <span class="s1">&#39;some_audio.ogg&#39;</span>
<span class="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">dev</span><span class="p">,</span> <span class="n">Context</span><span class="p">(</span><span class="n">dev</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Source</span><span class="p">()</span> <span class="k">as</span> <span class="n">src</span><span class="p">:</span>
<span class="n">dec</span> <span class="o">=</span> <span class="n">decode</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
</pre></div>
</div>
<p>We are almost there. Now, let’s look at the document for <a class="reference internal" href="../reference.html#palace.Decoder.play" title="palace.Decoder.play"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Decoder.play()</span></code></a>.
The method takes 3 parameters: <code class="docutils literal notranslate"><span class="pre">chunk_len</span></code>, <code class="docutils literal notranslate"><span class="pre">queue_size</span></code>, and <code class="docutils literal notranslate"><span class="pre">source</span></code>.</p>
<p>The source object is optional, because if you don’t have it, a new source
will be generated by default.</p>
<p>The audio is divided into chunks, each of which is of length <code class="docutils literal notranslate"><span class="pre">chunk_len</span></code>.
Then <code class="docutils literal notranslate"><span class="pre">queue_size</span></code> is the number of these chunks that it will play.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></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="n">filename</span> <span class="o">=</span> <span class="s1">&#39;some_audio.ogg&#39;</span>
<span class="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">dev</span><span class="p">,</span> <span class="n">Context</span><span class="p">(</span><span class="n">dev</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Source</span><span class="p">()</span> <span class="k">as</span> <span class="n">src</span><span class="p">:</span>
<span class="n">dec</span> <span class="o">=</span> <span class="n">decode</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
<span class="n">dec</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">src</span><span class="p">)</span>
</pre></div>
</div>
<p>But we don’t want it to play only a small part of the audio. We want it to
play all of it. How do we do that? The answer is a loop.</p>
<p>There is a method, <a class="reference internal" href="../reference.html#palace.Context.update" title="palace.Context.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Context.update()</span></code></a>, which update the context and the source.
When the source is updated, it will be filled with new chunks of data from
the decoder.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></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="n">filename</span> <span class="o">=</span> <span class="s1">&#39;some_audio.ogg&#39;</span>
<span class="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">dev</span><span class="p">,</span> <span class="n">Context</span><span class="p">(</span><span class="n">dev</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Source</span><span class="p">()</span> <span class="k">as</span> <span class="n">src</span><span class="p">:</span>
<span class="n">dec</span> <span class="o">=</span> <span class="n">decode</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
<span class="n">dec</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">src</span><span class="p">)</span>
<span class="k">while</span> <span class="n">src</span><span class="o">.</span><span class="n">playing</span><span class="p">:</span>
<span class="n">ctx</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
</pre></div>
</div>
<p>If you tried this code for a song, you will find that it’s a bit rush.
That is because the source is renewed too fast. So, a simple solution
is to <code class="docutils literal notranslate"><span class="pre">sleep</span></code> for a while.</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="n">filename</span> <span class="o">=</span> <span class="s1">&#39;some_audio.ogg&#39;</span>
<span class="k">with</span> <span class="n">Device</span><span class="p">()</span> <span class="k">as</span> <span class="n">dev</span><span class="p">,</span> <span class="n">Context</span><span class="p">(</span><span class="n">dev</span><span class="p">)</span> <span class="k">as</span> <span class="n">ctx</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Source</span><span class="p">()</span> <span class="k">as</span> <span class="n">src</span><span class="p">:</span>
<span class="n">dec</span> <span class="o">=</span> <span class="n">decode</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
<span class="n">dec</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">src</span><span class="p">)</span>
<span class="k">while</span> <span class="n">src</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">ctx</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
</pre></div>
</div>
<p>Congratulation! Enjoy your music before we get to the next part of this tutorial.</p>
</div>
</div>
</div>
<div class="related bottom">
&nbsp;
<nav id="rellinks">
<ul>
<li>
&larr;
<a href="context.html" title="Previous document">Context Creation</a>
</li>
<li>
<a href="../reference.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.0.3</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/tutorial/play-audio.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

1
src/index.rst
View File

@ -12,6 +12,7 @@ for a safe, convenient and pleasurable experience.
:maxdepth: 2
installation
tutorial/index
reference
design
contributing

41
src/tutorial/context.rst Normal file
View File

@ -0,0 +1,41 @@
.. py:currentmodule:: palace
Context Creation
================
A context is an object that allows palace to access OpenAL,
which is essential when you work with palace. Context maintains
the audio environment and contains environment settings and components
such as sources, buffers, and effects.
Creating a Device Object
------------------------
To create a context, we must first create a device,
since it's a parameter of the context object.
To create an object, well, you just have to instantiate
the :py:class:`Device` class.
.. code-block:: python
from palace import Device
with Device() as dev:
# Your code goes here
This is how you declare a :py:class:`Device` object with the default device.
There can be several devices available, which can be found
in :py:data:`device_names`.
Creating a Context
------------------
Now that we've created a device, we can create the context:
.. code-block:: python
from palace import Device, Context
with Device() as dev, Context(dev) as ctx:
# Your code goes here

15
src/tutorial/index.rst Normal file
View File

@ -0,0 +1,15 @@
Tutorial
========
This tutorial will guide you on:
.. toctree::
:maxdepth: 2
context
play-audio
.. comment these to add later
Moving sources
Adding effects
Customize decoder
Generate sounds

101
src/tutorial/play-audio.rst Normal file
View File

@ -0,0 +1,101 @@
.. py:currentmodule:: palace
Play an Audio
=============
Now that you know how to create a context,
let's get into the most essential use case: playing audio.
Creating a Source
-----------------
To play an audio, you have to create a source. This source
is an imaginary sound broadcaster, whose positions and properties
can be changed to create desired effects.
.. code-block:: python
from palace import Device, Context, Source
with Device() as dev, Context(dev) as ctx:
with Source() as src:
# to be written
Just like for the case of :py:class:`Context`, :py:class:`Source` creation
requires a context, but here the context is passed implicitly.
Decode the Audio File
---------------------
Palace has a module level function :py:func:`decode`, which decodes audio file
automatically, and this decoded file is a :py:class:`Decoder` object. This object
can be played by a simple :py:meth:`Decoder.play` method.
.. code-block:: python
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
We are almost there. Now, let's look at the document for :py:meth:`Decoder.play`.
The method takes 3 parameters: ``chunk_len``, ``queue_size``, and ``source``.
The source object is optional, because if you don't have it, a new source
will be generated by default.
The audio is divided into chunks, each of which is of length ``chunk_len``.
Then ``queue_size`` is the number of these chunks that it will play.
.. TODO: I think it's better to include a diagram here. Add later
.. code-block:: python
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
dec.play(12000, 4, src)
But we don't want it to play only a small part of the audio. We want it to
play all of it. How do we do that? The answer is a loop.
There is a method, :py:meth:`Context.update`, which update the context and the source.
When the source is updated, it will be filled with new chunks of data from
the decoder.
.. code-block:: python
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
dec.play(12000, 4, src)
while src.playing:
ctx.update()
If you tried this code for a song, you will find that it's a bit rush.
That is because the source is renewed too fast. So, a simple solution
is to ``sleep`` for a while.
.. code-block:: python
from time import sleep
from palace import Device, Context, Source, decode
filename = 'some_audio.ogg'
with Device() as dev, Context(dev) as ctx:
with Source() as src:
dec = decode(filename)
dec.play(12000, 4, src)
while src.playing:
sleep(0.025)
ctx.update()
Congratulation! Enjoy your music before we get to the next part of this tutorial.