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
83
84
85
86
87
88
89
90
91
|
# coding: utf-8
# Copyright 2020 DragonRuby LLC
# MIT License
# args_docs.rb has been released under MIT (*only this file*).
module ArgsDocs
def docs_method_sort_order
[
:docs_audio
]
end
def docs_audio
<<-S
* DOCS: ~GTK::Args#audio~
Hash that contains audio sources that are playing. If you want to add a new sound add a hash with keys/values as
in the following example:
#+begin_src
def tick args
# The values below (except for input of course) are the default values that apply if you don't
# specify the value in the hash.
args.audio[:my_audio] = {
input: 'sound/boom.wav', # Filename
x: 0.0, y: 0.0, z: 0.0, # Relative position to the listener, x, y, z from -1.0 to 1.0
gain: 1.0, # Volume (0.0 to 1.0)
pitch: 1.0, # Pitch of the sound (1.0 = original pitch)
paused: false, # Set to true to pause the sound at the current playback position
looping: false, # Set to true to loop the sound/music until you stop it
}
end
#+end_src
Sounds that don't specify ~looping: true~ will be removed automatically from the hash after the playback ends.
Looping sounds or sounds that should stop early must be removed manually.
** Audio synthesis (Pro only)
Instead of a path to an audio file you can specify an array ~[channels, sample_rate, sound_source]~ for ~input~
to procedurally generate sound. You do this by providing an array of float values between -1.0 and 1.0 that
describe the waveform you want to play.
- ~channels~ is the number of channels: 1 = mono, 2 = stereo
- ~sample_rate~ is the number of values per seconds you will provide to describe the audio wave
- ~sound_source~ The source of your sound. See below
*** Sound source
A sound source can be one of two things:
- A ~Proc~ object that is called on demand to generate the next samples to play. Every call should generate
enough samples for at least 0.1 to 0.5 seconds to get continuous playback without audio skips.
The audio will continue playing endlessly until removed, so the ~looping~ option will have no effect.
- An array of sample values that will be played back once. This is useful for procedurally generated one-off SFX.
~looping~ will work as expected
When you specify 2 for ~channels~, then the generated sample array will be played back in an interleaved manner.
The first element is the first sample for the left channel, the second element is the first sample for the right
channel, the third element is the second sample for the left channel etc.
*** Example:
#+begin_src
def tick args
sample_rate = 48000
generate_sine_wave = lambda do
frequency = 440.0 # A5
samples_per_period = (sample_rate / frequency).ceil
one_period = samples_per_period.map_with_index { |i|
Math.sin((2 * Math::PI) * (i / samples_per_period))
}
one_period * frequency # Generate 1 second worth of sound
end
args.audio[:my_audio] ||= {
input: [1, sample_rate, generate_sine_wave]
}
end
#+end_src
S
end
end
class GTK::Args
extend Docs
extend ArgsDocs
end
|
