diff --git a/supriya/ugens/core.py b/supriya/ugens/core.py index 7707367e9..a1ac714c5 100644 --- a/supriya/ugens/core.py +++ b/supriya/ugens/core.py @@ -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: @@ -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 ) @@ -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", @@ -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 ) @@ -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 @@ -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": @@ -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 ) @@ -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 ) @@ -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 @@ -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) @@ -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]] = [] @@ -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