~cnx/palace

ref: 708f23b35a7e232273ba0a63a65b3ef778a84540 palace/docs/source/tutorial/source.rst -rw-r--r-- 2.3 KiB
708f23b3 — Ngô Ngọc Đức Huy Write tutorial for source effect 1 year, 7 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
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