Skip to content

Commit

Permalink
Documenting
Browse files Browse the repository at this point in the history
  • Loading branch information
@josephine-wolf-oberholtzer
josephine-wolf-oberholtzer committed Apr 14, 2024
1 parent 211d5e6 commit b55a6eb
Showing 1 changed file with 229 additions and 10 deletions.
239 changes: 229 additions & 10 deletions supriya/ugens/core.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1722,6 +1722,13 @@ def __sub__(self, expr: "UGenRecursiveInput") -> "UGenOperable":
)

def __synthdef__(self) -> "SynthDef":
"""
Generate a SynthDef from UGen graph.
Typically used for rendering debug information about the UGen graph, or
for generating Graphviz graphs.
"""

def recurse(operable) -> None:
if isinstance(operable, UGenVector):
for x in operable:
Expand Down Expand Up @@ -1911,6 +1918,31 @@ def am_clip(self, expr: "UGenRecursiveInput") -> "UGenOperable":
)

def amplitude_to_db(self) -> "UGenOperable":
"""
Convert UGen graph from amplitude to decibels.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.amplitude_to_db()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(AMPLITUDE_TO_DB).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(AMPLITUDE_TO_DB).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(
source=self, special_index=UnaryOperator.AMPLITUDE_TO_DB
)
Expand Down Expand Up @@ -1960,13 +1992,6 @@ def atan2(self, expr: "UGenRecursiveInput") -> "UGenOperable":
float_operator=math.atan2,
)

def ceiling(self) -> "UGenOperable":
return _compute_unary_op(
source=self,
special_index=UnaryOperator.CEILING,
float_operator=math.ceil,
)

def clip(
self,
minimum: "UGenRecursiveInput",
Expand Down Expand Up @@ -2003,6 +2028,31 @@ def cubed(self) -> "UGenOperable":
return _compute_unary_op(source=self, special_index=UnaryOperator.CUBED)

def db_to_amplitude(self) -> "UGenOperable":
"""
Convert UGen graph from decibels to amplitude.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.db_to_amplitude()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(DB_TO_AMPLITUDE).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(DB_TO_AMPLITUDE).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(
source=self, special_index=UnaryOperator.DB_TO_AMPLITUDE
)
Expand All @@ -2024,9 +2074,6 @@ def distort(self) -> "UGenOperable":
def exponential(self) -> "UGenOperable":
return _compute_unary_op(source=self, special_index=UnaryOperator.EXPONENTIAL)

def floor(self) -> "UGenOperable":
return _compute_unary_op(source=self, special_index=UnaryOperator.FLOOR)

def fractional_part(self) -> "UGenOperable":
return _compute_unary_op(
source=self, special_index=UnaryOperator.FRACTIONAL_PART
Expand Down Expand Up @@ -2060,9 +2107,59 @@ def hypotx(self, expr: "UGenRecursiveInput") -> "UGenOperable":
)

def hz_to_midi(self) -> "UGenOperable":
"""
Convert UGen graph from Hertz to MIDI note number.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.hz_to_midi()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(HZ_TO_MIDI).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(HZ_TO_MIDI).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(source=self, special_index=UnaryOperator.HZ_TO_MIDI)

def hz_to_octave(self) -> "UGenOperable":
"""
Convert UGen graph from Hertz to octave number.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.hz_to_octave()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(HZ_TO_OCTAVE).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(HZ_TO_OCTAVE).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(source=self, special_index=UnaryOperator.HZ_TO_OCTAVE)

def is_equal_to(self, expr: "UGenRecursiveInput") -> "UGenOperable":
Expand Down Expand Up @@ -2103,12 +2200,87 @@ def log10(self) -> "UGenOperable":
return _compute_unary_op(source=self, special_index=UnaryOperator.LOG10)

def midi_to_hz(self) -> "UGenOperable":
"""
Convert UGen graph from MIDI note number to Hertz.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.midi_to_hz()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(MIDI_TO_HZ).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(MIDI_TO_HZ).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(source=self, special_index=UnaryOperator.MIDI_TO_HZ)

def octave_to_hz(self) -> "UGenOperable":
"""
Convert UGen graph from octave number to Hertz.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.octave_to_hz()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(OCTAVE_TO_HZ).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(OCTAVE_TO_HZ).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(source=self, special_index=UnaryOperator.OCTAVE_TO_HZ)

def ratio_to_semitones(self) -> "UGenOperable":
"""
Converts UGen graph from frequency ratio to semitone distance.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.ratio_to_semitones()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(RATIO_TO_SEMITONES).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(RATIO_TO_SEMITONES).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(
source=self, special_index=UnaryOperator.RATIO_TO_SEMITONES
)
Expand Down Expand Up @@ -2197,6 +2369,31 @@ def scale_negative(self, expr: "UGenRecursiveInput") -> "UGenOperable":
)

def semitones_to_ratio(self) -> "UGenOperable":
"""
Converts UGen graph from semitone distance to frequency ratio.
::
>>> from supriya.ugens import SinOsc
>>> ugen_graph = SinOsc.ar(frequency=[440, 443])
>>> result = ugen_graph.semitones_to_ratio()
>>> supriya.graph(result) # doctest: +SKIP
>>> print(result)
synthdef:
name: ...
ugens:
- SinOsc.ar/0:
frequency: 440.0
phase: 0.0
- UnaryOpUGen(SEMITONES_TO_RATIO).ar/0:
source: SinOsc.ar/0[0]
- SinOsc.ar/1:
frequency: 443.0
phase: 0.0
- UnaryOpUGen(SEMITONES_TO_RATIO).ar/1:
source: SinOsc.ar/1[0]
"""
return _compute_unary_op(
source=self, special_index=UnaryOperator.SEMITONES_TO_RATIO
)
Expand Down Expand Up @@ -2282,6 +2479,12 @@ class UGenScalar(UGenOperable):


class OutputProxy(UGenScalar):
"""
A UGen output proxy.
Encodes a reference to a specific output of a UGen, as a scalar.
"""

def __init__(self, ugen: "UGen", index: int) -> None:
self.ugen = ugen
self.index = index
Expand All @@ -2308,6 +2511,12 @@ def calculation_rate(self) -> CalculationRate:


class ConstantProxy(UGenScalar):
"""
A floating point constant proxy.
Wraps a float and exposes all UGenOperable methods against it.
"""

def __init__(self, value: SupportsFloat) -> None:
self.value = float(value)

Expand All @@ -2327,6 +2536,9 @@ def __str__(self) -> str:


class UGenVector(UGenOperable, Sequence[UGenOperable]):
"""
A sequence of UGenOperables.
"""

def __init__(self, *values: Union[SupportsFloat, UGenOperable]) -> None:
values_: List[Union[UGen, UGenScalar, UGenVector]] = []
Expand Down Expand Up @@ -2378,11 +2590,18 @@ def sum(self) -> UGenOperable:

@runtime_checkable
class UGenSerializable(Protocol):
"""
Protocol for classes serializable as UGenVectors.
"""

def serialize(self, **kwargs) -> UGenVector:
pass


class UGen(UGenOperable, Sequence):
"""
A UGen: a "unit generator".
"""

_channel_count = 1
_has_done_flag = False
Expand Down

0 comments on commit b55a6eb

Please sign in to comment.