.. This file is auto-generated by the Sphinx pre-build hook in ``documentation/source/conf.py`` from ``documentation/source/_data/patcher_objects.json`` and the notes in ``documentation/source/_data/patcher_notes/``. Do not edit by hand — re-run ``python yse.py dump-patcher-meta`` to refresh the JSON, then ``make html`` to re-render this page. Math ==== Arithmetic, comparison, conversion, scaling and analysis of numbers. 69 objects. Every entry is pulled directly from the engine source via the ``ADD_DESCRIPTION`` / ``INLET_DOC`` / ``OUTLET_DOC`` / ``PARAM_DOC`` macros (see :file:`YseEngine/patcher/pObject.h`). The ``~`` prefix marks DSP / audio-rate objects; ``.`` marks control-rate objects. .. contents:: :local: :depth: 1 ``.!-`` ------- Subtracts the left operand from the right one and sends right - left as a float: .- with the operands the other way round. :Kind: Control-rate Use it when the value that should trigger the calculation is the one being subtracted: .. code-block:: text [.!- 100] 30 -> left inlet => 70 The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand, the value subtracted; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - right - left. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.!/`` ------- Divides the right operand by the left one and sends right / left as a float: ./ with the operands the other way round. A left operand of 0 sends 0. :Kind: Control-rate Use it when the value that should trigger the calculation is the divisor. A left operand of 0 sends 0. .. code-block:: text [.!/ 1] 4 -> left inlet => 0.25 The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand, the divisor; sends the result. 0 makes the result 0. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - right / left, or 0 when left is 0. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.!=`` ------- Sends 1 when the left operand differs from the right one, otherwise 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when left != right, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.%`` ------ Sends the remainder of dividing the left operand by the right one, as an int. The remainder has the sign of the left operand, and a divisor of 0 sends 0. :Kind: Control-rate Works on whole numbers: a float on either inlet is truncated toward zero first, so 7.9 counts as 7. The remainder has the sign of the left operand, so -1 stays -1 rather than wrapping round: .. code-block:: text [.% 12] 14 => 2 [.% 12] -1 => -1 To wrap a number that can go negative into a range, use ``.pong`` with mode 2 (``.pong 0 12 2``), which sends 11 for -1. A divisor of 0 sends 0. ``.div`` sends the quotient that goes with the remainder. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any int - Dividend; sends the result. Floats are truncated toward zero. * - 1 - right - FLOAT, INT - any int - Divisor, stored for the next result. Floats are truncated toward zero; 0 makes the result 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - The remainder of left / right, or 0 when right is 0. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any int - Starting divisor. ``.&`` ------ Bitwise AND of two integers, sent as an int. Floats are truncated toward zero first. :Kind: Control-rate **The bitwise objects** ``.&``, ``.|``, ``.<<`` and ``.>>`` work on 32-bit whole numbers and send an int. A float on either inlet is truncated toward zero first. - ``.&`` keeps the bits set in both operands, so ``.& 15`` keeps the lowest four bits: 300 gives 12. - ``.|`` keeps the bits set in either operand. - ``.<<`` shifts bits up: ``.<< 4`` turns 3 into 48. Bits shifted past the top are lost, and a count of 32 or more gives 0. - ``.>>`` shifts bits down and keeps the sign, so -8 shifted by 1 is -4. A count of 32 or more gives -1 for a negative number and 0 for any other. A shift count below 0 shifts nothing. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any int - Left operand; sends the result. Floats are truncated toward zero. * - 1 - right - FLOAT, INT - any int - Right operand, stored for the next result. Floats are truncated toward zero. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - The bitwise AND of both operands. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any int - Starting right operand. ``.&&`` ------- Logical AND: sends 1 when both operands are non-zero, otherwise 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when both operands are non-zero, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.*`` ------ Multiplies two numbers and sends the product as a float. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - left * right. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.+`` ------ Adds two numbers. A number on the left inlet is added to the stored right operand, and the sum is sent as a float. :Kind: Control-rate **Hot and cold inlets** The left inlet is hot: a number there is stored and the result is sent at once. Every other inlet is cold: it stores its number for the next result and sends nothing. The creation argument sets the right operand, which is 0 until it is given. .. code-block:: text [.+ 10] 5 -> left inlet => 15 3 -> right inlet, then 5 -> left inlet => 8 Every math object with more than one inlet works this way unless its notes say otherwise. To set both operands from one message, update the cold inlet first: ``.trigger`` sends from its rightmost outlet to its leftmost, so wire its right outlet to the cold inlet and its left outlet to the hot one. ``.swap`` sends a pair in that order, and ``.!-`` and ``.!/`` are ``.-`` and ``./`` with the operands the other way round. **Numbers** Ints and floats are both accepted. A bang, a list or a word is ignored, so to calculate again, send the left value again. ``.+``, ``.-``, ``.*``, ``./``, ``.!-`` and ``.!/`` calculate in floats and send a float, even for two ints. A float holds whole numbers exactly only up to 16,777,216; above that, ints lose precision. Dividing by 0 sends 0. Use ``.%`` and ``.div`` for whole-number division. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - left + right. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.-`` ------ Subtracts the right operand from the left one and sends the difference as a float. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - left - right. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``./`` ------ Divides the left operand by the right one and sends the quotient as a float. Dividing by 0 sends 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Dividend; sends the result. * - 1 - right - FLOAT, INT - any float - Divisor, stored for the next result. 0 makes the result 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - left / right, or 0 when right is 0. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting divisor. ``.<`` ------ Sends 1 when the left operand is less than the right one, otherwise 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when left < right, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.<<`` ------- Shifts the bits of the left operand left by the right operand. A count below 0 shifts nothing, and a count of 32 or more gives 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any int - Left operand; sends the result. Floats are truncated toward zero. * - 1 - right - FLOAT, INT - any int - Right operand, stored for the next result. Floats are truncated toward zero. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - The left operand shifted left by the right operand. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any int - Starting right operand. ``.<=`` ------- Sends 1 when the left operand is less than or equal to the right one, otherwise 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when left <= right, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.==`` ------- Sends 1 when the left operand equals the right one, otherwise 0. :Kind: Control-rate **The comparison and logic objects** ``.==``, ``.!=``, ``.<``, ``.<=``, ``.>``, ``.>=``, ``.&&`` and ``.||`` send 1 when their test holds and 0 when it does not, as an int. Ints and floats are compared by value, so 3 equals 3.0. The test is exact. A value that ought to be 1 but arrives as 0.9999999 after some arithmetic is not equal to 1; send it through ``.round`` first. ``.&&`` and ``.||`` treat any number other than 0 as true, including negative numbers and fractions such as 0.5. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when left == right, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.>`` ------ Sends 1 when the left operand is greater than the right one, otherwise 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when left > right, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.>=`` ------- Sends 1 when the left operand is greater than or equal to the right one, otherwise 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when left >= right, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``.>>`` ------- Shifts the bits of the left operand right by the right operand, keeping the sign. A count below 0 shifts nothing; past 31, a negative number gives -1 and any other 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any int - Left operand; sends the result. Floats are truncated toward zero. * - 1 - right - FLOAT, INT - any int - Right operand, stored for the next result. Floats are truncated toward zero. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - The left operand shifted right by the right operand. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any int - Starting right operand. ``.abs`` -------- Sends the absolute value of a number, as a float. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - 0 or higher - The absolute value of the input. ``.accum`` ---------- Stores a number you can replace, add to and multiply. A number on the left inlet replaces it and sends it; the middle inlet adds to it and the right inlet multiplies it, without sending. :Kind: Control-rate The middle and right inlets change the stored value without sending it, unlike the cold inlets of the other math objects, which only store an operand. **Messages** - a number on the left inlet: replace the stored value and send it. - bang: send the stored value. - ``set ``: replace the stored value without sending it. - ``add ``: add without sending, as the middle inlet does. ``ft1 `` is another spelling of the same message. - ``mult ``: multiply without sending, as the right inlet does. - ``reset``: go back to the creation argument without sending. On an ``.accum 1`` that is 1, not 0. A word without a number after it is ignored. .. code-block:: text [.accum 1] mult 2, mult 2, bang => 4 The stored value is a float; there is no whole-number mode, so put ``.round`` after the outlet to get whole numbers. The value never becomes infinite: it stops at about plus or minus 3.4e38, and a later multiply brings it back. An infinite or undefined number (NaN) changes nothing when it is added or multiplied, and counts as 0 when it replaces the stored value. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - value - FLOAT, INT, BANG, LIST - any float - Number: replace the stored value and send it. Bang: send the stored value. 'set ', 'add ', 'mult ': replace, add or multiply without sending. 'reset': go back to the starting value. * - 1 - add - FLOAT, INT - any float - Number added to the stored value, without sending. * - 2 - mult - FLOAT, INT - any float - Number the stored value is multiplied by, without sending. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The stored value. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - initial - 0 - any float - Starting value: what a bang sends before anything changes it, and what 'reset' returns to. ``.acos`` --------- Sends the arc-cosine of a number, in radians. Numbers outside -1 to 1 send 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - -1.0 to 1.0 - Number; sends the result. Numbers outside -1 to 1 send 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - 0 to pi - The arc-cosine of the input, in radians. ``.acosh`` ---------- Sends the hyperbolic arc-cosine of a number. Numbers below 1 send 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - 1.0 or higher - Number; sends the result. Numbers below 1 send 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - 0 or higher - The hyperbolic arc-cosine of the input. ``.anal`` --------- Counts how often each number follows the one before it, and sends ' ' for every pair it counts. Wire it into .prob to make .prob play in the style of what it heard. :Kind: Control-rate Every number after the first is counted as a pair with the number before it, and the pair leaves with its new count. The first number only becomes the one the next number is paired with. .. code-block:: text 60, 62, 60, 62 => 60 62 1, 62 60 1, 60 62 2 Numbers are limited to 0 to ``limit``, and floats are truncated, so with the default of 128 MIDI note numbers arrive unchanged. Wire the outlet into ``.prob``: each list sets the weight of that transition in ``.prob`` to the count, so ``.prob`` learns which numbers follow which and can play in the same style. **Messages** - ``clear``: forget the counts, but keep the last number, so the next number still forms a pair with it. - ``reset``: forget the last number but keep the counts, so the next number starts a new phrase. - ``dump``: send every stored pair with its count, in the order the pairs were first seen. Use it to teach a ``.prob`` created later. **Limits** At most 1024 different pairs are stored. Once the table is full, pairs already in it keep counting, and a new pair is not stored: outlet 1 bangs instead. A count stops growing at 1,048,576. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, LIST - 0 to limit - Number: count it as following the previous number. 'clear': forget the counts. 'reset': forget the previous number. 'dump': send every stored pair. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - pair - LIST - — - ' ': how often this pair has been seen. * - 1 - full - BANG - — - Bang when a new pair cannot be stored because 1024 different pairs already are. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - limit - 128 - 1-16384 - Highest number accepted; numbers are limited to 0 to limit. Clamped to 1-16384. ``.asin`` --------- Sends the arc-sine of a number, in radians. Numbers outside -1 to 1 send 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - -1.0 to 1.0 - Number; sends the result. Numbers outside -1 to 1 send 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - -pi/2 to pi/2 - The arc-sine of the input, in radians. ``.asinh`` ---------- Sends the hyperbolic arc-sine of a number. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The hyperbolic arc-sine of the input. ``.atan`` --------- Sends the arc-tangent of a number, in radians. Use .atan2 for an angle around the full circle. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - -pi/2 to pi/2 - The arc-tangent of the input, in radians. ``.atan2`` ---------- Sends the angle of the point (x, y) in radians, measured from the positive x axis, from -pi to pi. The left inlet takes y and the right inlet x. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - y - FLOAT, INT - any float - y coordinate; sends the result. * - 1 - x - FLOAT, INT - any float - x coordinate, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - -pi to pi - The angle of (x, y) in radians. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - x - 0 - any float - Starting x coordinate. ``.atanh`` ---------- Sends the hyperbolic arc-tangent of a number. Numbers at or beyond -1 and 1 send 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - greater than -1.0 and less than 1.0 - Number; sends the result. Numbers at or beyond -1 and 1 send 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The hyperbolic arc-tangent of the input. ``.atodb`` ---------- Converts a linear amplitude to decibels on the engine's scale, where an amplitude of 1 is 100 dB and nothing goes below 0 dB. Subtract 100 for decibels relative to full scale. :Kind: Control-rate **The engine's decibel scale** ``.atodb`` and ``.dbtoa`` use the scale the engine uses for its own volume levels: an amplitude of 1 is 100 dB, and every halving of the amplitude is about 6 dB less. An amplitude of 0.00001 and anything quieter gives 0, so the result never goes negative. .. code-block:: text 1 => 100 0.5 => 93.98 0.1 => 80 Subtract 100 to read the result as decibels relative to full scale, and add 100 to such a value before sending it to ``.dbtoa``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - 0.0 and up - Linear amplitude; sends the result. 0 and below send 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - 0-485 dB - The amplitude in decibels; 100 dB is an amplitude of 1. ``.cartopol`` ------------- Converts the point (x, y) to polar form: its distance from the origin on the left outlet and its angle in radians on the right one. :Kind: Control-rate Both outlets send on every calculation, the angle first, so an object that takes both values already has the angle when the distance arrives. The angle is measured counterclockwise from the positive x axis, from -pi to pi. ``.poltocar`` converts back. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - x - FLOAT, INT - any float - x coordinate; sends the result. * - 1 - y - FLOAT, INT - any float - y coordinate, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - amplitude - FLOAT - 0 or higher - Distance of (x, y) from the origin. Sent after the angle. * - 1 - angle - FLOAT - -pi to pi - Angle of (x, y) in radians, measured from the positive x axis. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - y - 0 - any float - Starting y coordinate. ``.change`` ----------- Passes a number on only when it differs from the previous one. Two more outlets report when the value leaves 0 and when it returns to 0. :Kind: Control-rate The first number is compared with the creation argument, 0 by default. A bare ``.change`` therefore ignores a first 0, and ``.change 5`` stays silent until the value moves away from 5, so loading a patch does not report a parameter that has not moved. The comparison is exact: 0.5 and 0.5000001 are different numbers. To ignore small changes, put ``.round`` in front. **Outlets** - left: the number, when it differs from the previous one. - middle: 1 when the value changes from 0 to anything else. - right: 1 when the value changes from anything else to 0. The outlets send from right to left, so whatever the number triggers already has the 0 reports. ``.togedge`` reports the same two changes as bangs. **Modes** - ``mode +``: send 1 when the number is greater than the previous one. - ``mode -``: send -1 when the number is less than the previous one. - ``mode``: back to sending numbers that differ. A ``+`` or ``-`` after the creation argument starts the object in that mode. In every mode the previous number is the last one received, whether it was sent or not: a ``.change +`` fed 5, 3, 4 sends 1 (5 is above the starting 0), nothing, then 1. **Messages** - ``set ``: store n as the previous number without sending anything, for when the value was changed by another route. - ``reset``: go back to the creation value and mode without sending. A list counts as its first number. A bang, a word and an infinite or undefined number (NaN) are ignored. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, LIST - any float - Number to compare with the previous one. 'set ': store n without sending. 'mode +', 'mode -', 'mode': choose what counts as a change. 'reset': go back to the creation arguments. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The number, when it differs from the previous one. In mode + it sends 1 for a rise, and in mode - it sends -1 for a fall. * - 1 - rising - INT - 1 - 1 when the value changes from 0 to anything else. * - 2 - falling - INT - 1 - 1 when the value changes from anything else to 0. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - initial mode - 0 - a float, optionally followed by + or - - The value the first number is compared with, 0 by default, optionally followed by + or - to start in that mode. ``.clip`` --------- Limits a number to the range low to high and sends it as a float. A number inside the range passes unchanged; any other becomes the nearest limit. :Kind: Control-rate The limits may be given in either order: ``.clip 1 -1`` clips like ``.clip -1 1``. An undefined number (NaN) becomes 0 before it is clipped, so the result is always inside the range. ``~clip`` does the same to an audio signal. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - value - FLOAT, INT - any float - Number to limit; sends the result. * - 1 - low - FLOAT, INT - any float - Lower limit, stored for the next result. * - 2 - high - FLOAT, INT - any float - Upper limit, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - low to high - The number limited to the range. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - low - -1 - any float - Lower limit. * - high - 1 - any float - Upper limit. ``.cos`` -------- Sends the cosine of an angle in radians, as a float. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float (radians) - Angle in radians; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - -1.0 to 1.0 - The cosine of the input. ``.cosh`` --------- Sends the hyperbolic cosine of a number. Beyond about -89 and 89 the result is too large for a float, and 0 is sent. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - 1.0 or higher - The hyperbolic cosine of the input. ``.counter`` ------------ Counts bangs. Each bang adds the step to the count and sends the new count as an int; an int on the left inlet sets the count and sends it. :Kind: Control-rate The first bang sends the start value plus the step, so ``.counter 0 1`` sends 1, 2, 3 and so on. Create it as ``.counter -1`` to send 0 first. An int on the left inlet sets the count and sends it; the next bang adds the step to that. ``reset`` goes back to the start value without sending. Floats are ignored on both inlets. The count has no limit and does not wrap. To make it loop, send it through ``.%`` or ``.pong``, or reset it. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - control - INT, BANG, LIST - any int - Bang: add the step and send the count. Int: set the count and send it. 'reset': go back to the start value without sending. Floats are ignored. * - 1 - step - INT - any int - Step added on each bang. Floats are ignored. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - The count. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - startValue - 0 - any int - The count before the first bang, and the count 'reset' returns to. The first bang sends it plus the step. * - step - 1 - any int - Starting step; may be negative to count down. ``.dbtoa`` ---------- Converts decibels on the engine's scale to a linear amplitude: 100 dB is an amplitude of 1, and 0 dB or less gives 0. The inverse of .atodb. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - 0-485 dB - Decibels; sends the result. 0 and below send 0; above 485 counts as 485. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - 0.0 and up - The linear amplitude; 1 means 100 dB. ``.div`` -------- Integer division: divides the left operand by the right one and sends the whole quotient as an int, truncated toward zero. A divisor of 0 sends 0. :Kind: Control-rate The quotient is truncated toward zero, so -7 divided by 2 is -3, and floats are truncated before the division. ``.%`` sends the matching remainder. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any int - Dividend; sends the result. Floats are truncated toward zero. * - 1 - right - FLOAT, INT - any int - Divisor, stored for the next result. Floats are truncated toward zero; 0 makes the result 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - left / right truncated toward zero, or 0 when right is 0. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any int - Starting divisor. ``.expr`` --------- Evaluates a C-style expression such as '$f1 * 2 + $f2'. The placeholders $i1-$i9 and $f1-$f9 create the inlets; the left inlet calculates and sends the result. :Kind: Control-rate **Placeholders** ``$i1`` to ``$i9`` read an inlet as an int, truncated toward zero; ``$f1`` to ``$f9`` read it as a float. The number is the inlet, counted from 1 at the left. The object has as many inlets as the highest placeholder, and an inlet that is skipped, such as inlet 2 in ``$f1 + $f3``, is there but unused. An inlet that has not received a number reads 0. **Types** Types follow C: - ``+``, ``-``, ``*``, ``/`` and ``%`` on two ints give an int, so ``$i1 / $i2`` is whole-number division. With a float on either side, the result is a float. - Comparisons (``< <= > >= == !=``), logic (``&& || !``) and bitwise operators (``& | ^ << >> ~``) give an int. ``^`` is exclusive or, not a power: use ``pow()``. - The result leaves as an int or a float to match. .. code-block:: text [.expr ($f1 - 32) * 5 / 9] 212 => 100, a float [.expr $i1 / 2] 7 => 3, an int **Functions** ``min``, ``max``, ``abs``, ``int``, ``float``, ``pow``, ``sqrt``, ``exp``, ``ln`` and ``log`` (both the natural logarithm), ``log10``, ``sin``, ``cos``, ``tan``, ``asin``, ``acos``, ``atan``, ``atan2``, ``sinh``, ``cosh``, ``tanh``, ``fact`` (factorial), ``round``, ``floor`` and ``ceil``. ``int``, ``float``, ``abs``, ``min`` and ``max`` keep ints as ints; the others return a float. Division by 0, and any result that is not a finite number, give 0. **Input** A list on the left inlet fills the inlets from the left and calculates. Items past the ninth are ignored, and inlets the list does not reach keep their numbers. A bang calculates again with the stored numbers. The other inlets take single numbers. **Errors** An expression that cannot be read is reported in the log when the object is created, and the object then sends 0. Random numbers (``random``, ``noise``) and table functions (``size``, ``sum``, ``avg``, ``store`` and ``$s`` placeholders) are not supported and are reported the same way; use ``.random`` for random numbers. The expression is read once, when the object is created, so evaluating it is cheap and safe on the audio thread. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - $1 - FLOAT, INT, BANG, LIST - any float - Value for $i1 and $f1; sends the result. Bang: calculate again. List: fill the inlets from the left, then calculate. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - ANY - any float - The result: an int when the expression's type is int, otherwise a float. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - expression - — - any expression - The expression, for example "($f1 * 0.5) + pow($f2, 2)". Its placeholders decide how many inlets there are. ``.ftom`` --------- Converts a frequency in Hz to a MIDI note number, with 440 Hz (A4) at note 69. The result is fractional, so a detuned pitch keeps its offset. :Kind: Control-rate The scale is equal temperament with 12 notes per octave: 440 Hz is 69, 880 Hz is 81, and 450 Hz is about 69.39. A frequency of 0 or below has no note, so it gives -1500, which ``.mtof`` turns back into a frequency of almost 0. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - freq - FLOAT, INT - 0-20000 Hz - Frequency in Hz; sends the result. 0 Hz or below gives -1500. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - midi - FLOAT - any float - MIDI note number, with a fractional part. ``.histo`` ---------- Counts how often each number arrives and sends ' ' each time. The right inlet reports a number's count without counting it. :Kind: Control-rate Numbers from 0 to ``size`` - 1 are counted; floats are truncated. A number outside that range is not counted: outlet 1 bangs instead. With the default size of 128, MIDI note numbers fit. **Inlets and messages** - a number on the left inlet: count it and send it with its new count. - a number on the right inlet: send it with its count, without counting it. - bang: send the last counted number and its count again; ``0 0`` before anything was counted. - ``clear``: set every count to 0. The last number is kept, so a bang then reports it with a count of 0. - ``dump``: send every number with a count above 0, lowest first. Changing the ``size`` argument clears the counts. A count stops growing at 1,073,741,824. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - 0 to size-1 - Number: count it and send its count. Bang: send the count of the last counted number again. 'clear': set every count to 0. 'dump': send every number counted so far. * - 1 - query - FLOAT, INT - 0 to size-1 - Number: send its count without counting it. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - count - LIST - — - ' ': how often this number has been counted. * - 1 - reject - BANG - — - Bang when a number is outside 0 to size-1; it is not counted. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - size - 128 - 1-4096 - How many numbers can be counted: 0 to size-1. Clamped to 1-4096. ``.linedrive`` -------------- Maps a number onto an exponential curve: inputMax gives outputMax, and each step below it divides the output by the curve. Lets a linear control, such as a MIDI controller, drive a frequency or a gain evenly. :Kind: Control-rate The output is ``outputMax * curve ^ (value - inputMax)``. With the defaults, a 0-127 controller covers a wide range evenly: .. code-block:: text [.linedrive 127 1 1.06] 127 => 1 64 => about 0.025 0 => about 0.0006 Values above ``inputMax`` give more than ``outputMax``; nothing is limited, so add ``.clip`` when that matters. A curve below 1 mirrors the response, so the output grows as the value falls, and a curve of 1 always sends ``outputMax``. A curve of 0 or below, or a result too large for a float, sends 0. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - value - FLOAT, INT - any float - Number to map; sends the result. * - 1 - inputMax - FLOAT, INT - any float - Input that gives outputMax, stored for the next result. * - 2 - outputMax - FLOAT, INT - any float - Output at inputMax, stored for the next result. * - 3 - curve - FLOAT, INT - greater than 0 - Curve base, stored for the next result. Larger is steeper; 1 gives a constant outputMax; 0 or below sends 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The number mapped onto the curve. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - inputMax - 127 - any float - Input that gives outputMax. * - outputMax - 1 - any float - Output at inputMax. * - curve - 1.06 - greater than 0 - Curve base. Larger is steeper; 1 gives a constant outputMax. ``.maximum`` ------------ Sends the larger of a number and a stored value. The right inlet sets the stored value; a list sends its largest item. :Kind: Control-rate Numbers on the left inlet are compared with the stored value but never change it. For the largest number received so far, use ``.peak``. **Messages** - a number: send the larger of it and the stored value. - bang: send the last result again. Before the first result, that is the creation argument. - a list of two or more numbers: send the largest item. The stored value takes no part, and afterwards the second largest item becomes the stored value. Up to 256 items are read; a one-item list counts as a number. .. code-block:: text [.maximum 0.1] 0.05 => 0.1 0.3 => 0.3 3 9 4 => 9, and 4 is now the stored value With a control on the right inlet, ``.maximum`` is a lower limit that can move. The result is always a float. An infinite or undefined number (NaN) counts as 0. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any float - Number: send the larger of it and the stored value. Bang: send the last result again. List: send its largest item, and store the second largest. * - 1 - compare - FLOAT, INT - any float - Value to compare with, stored without sending. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The larger of the input and the stored value. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - initial - 0 - any float - Starting value to compare with, and what a bang sends before the first result. ``.mean`` --------- Sends the average of every number received so far, and how many numbers that is. A list sends the average of its own items and starts the average over. :Kind: Control-rate The count leaves before the average, so whatever the average triggers already has the matching count. **Messages** - a number: add it and send the new average. - bang: send the average and count again; 0 and 0 before any number. - a list: send the average of its items (up to 256) and start over from them. Numbers that arrive later are averaged with the list's items. - ``clear`` or ``reset``: start over without sending. Every number counts the same however long the average runs; the sum is kept in double precision, so it stays accurate over billions of numbers. An infinite or undefined number (NaN) counts as 0 and is still counted. The count outlet stops at 2,147,483,647, but the average stays correct. For an average that forgets old numbers, use ``.slide``, or ``.array.stream`` with ``.array.mean``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any float - Number: add it to the average and send. Bang: send the average again. List: average its items, forgetting earlier numbers. 'clear' or 'reset': start over without sending. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - mean - FLOAT - between the smallest and largest input - The average; 0 before any number has arrived. * - 1 - count - INT - 0 and up - How many numbers the average includes. Sent before the average. ``.minimum`` ------------ Sends the smaller of a number and a stored value. The right inlet sets the stored value; a list sends its smallest item. :Kind: Control-rate Works like ``.maximum`` with the comparison reversed: a list sends its smallest item, and the second smallest becomes the stored value. The stored value starts at 0, so a bare ``.minimum`` sends 0 for every positive number. Give it an argument, or a number on the right inlet. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any float - Number: send the smaller of it and the stored value. Bang: send the last result again. List: send its smallest item, and store the second smallest. * - 1 - compare - FLOAT, INT - any float - Value to compare with, stored without sending. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The smaller of the input and the stored value. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - initial - 0 - any float - Starting value to compare with, and what a bang sends before the first result. ``.mtof`` --------- Converts a MIDI note number to a frequency in Hz, with note 69 (A4) at 440 Hz. Fractional note numbers give the frequencies in between. :Kind: Control-rate The scale is equal temperament with 12 notes per octave: 69 is 440 Hz, 60 (middle C) is about 261.63 Hz, and 69.5 is a quarter tone above A4. Note numbers outside 0-127 work too, from -1500 to 1499: a higher note is treated as 1499, and a lower one gives 0 Hz. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - midi - FLOAT, INT - 0-127 - MIDI note number, fractional values included; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - freq - FLOAT - 8.18-12543 Hz - Frequency in Hz. ``.past`` --------- Sends a bang when a number rises to or above a threshold, then stays silent until the number drops below it again. With several thresholds, each item of a list must reach its own. :Kind: Control-rate A number has reached its threshold when it is equal to it or above. The object bangs when the number reaches the threshold after being below it, and is ready again only once the number drops strictly below: .. code-block:: text [.past 100] 80, 110, 120, 90, 105 => bang at 110, bang at 105 [.past 5] 10, 5, 10 => one bang, at the first 10 A new object bangs on the first number that reaches the threshold. **Several thresholds** ``.past 60 100`` compares a list item by item: the first item with 60, the second with 100. It bangs when every item has reached its threshold. A list with fewer items updates only those positions, a number is the first item, and items past the last threshold are ignored. At most 256 thresholds are held. **Messages** - ``clear``: forget the past, so the next number that reaches the thresholds bangs again. The thresholds are kept. - ``set ``: change the thresholds. This does not clear: a threshold that is changed continually does not cause a bang for every message above it. Positions the new list adds start below their threshold. - ``reset``: go back to the creation thresholds and clear. None of them sends anything. A bang is ignored, and an infinite or undefined number (NaN) counts as 0, in the input and in the thresholds. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, LIST - any list of floats - Number or list to compare with the thresholds. 'clear': let the next crossing bang again. 'set ': change the thresholds. 'reset': go back to the creation thresholds. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - cross - BANG - bang - Bang when every item has reached its threshold, having not done so before. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - thresholds - 0 - any list of floats - The thresholds, one per list position. A single 0 by default; at most 256. ``.peak`` --------- Keeps the largest number received so far and sends it only when a new number beats it. Two more outlets report whether each number set a new peak. :Kind: Control-rate **Inlets and messages** - a number on the left inlet: when it is greater than the peak, it becomes the peak and is sent. A number equal to the peak is not a new peak. - a number on the right inlet: it becomes the peak and is sent, and counts as new even when it is lower. - bang: send the peak from the left outlet only. - a list `` ``: set the peak as the right inlet does, then offer the number. Items past the second are ignored. - ``set ``: set the peak without sending. - ``reset``: go back to the creation argument without sending. Every number sends the two flag outlets, right before middle, and then the new peak if there is one. .. code-block:: text [.peak] 3, 5, 4, 9 => 3, 5, (nothing), 9 The peak starts at 0, so negative numbers never beat it. For data below 0, give a lower start, such as ``.peak -1000``. The result is always a float, and an infinite or undefined number (NaN) counts as 0. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any float - Number: send it if it beats the peak. Bang: send the peak. List ' ': set the peak, then offer the number. 'set ': set the peak without sending. 'reset': go back to the starting peak without sending. * - 1 - seed - FLOAT, INT - any float - Number that becomes the new peak and is sent, always reported as a new record. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The new peak. Silent when a number does not beat it. * - 1 - new - INT - 0 or 1 - 1 when the number just received set a new record, otherwise 0. * - 2 - same - INT - 0 or 1 - The opposite of the 'new' outlet: 0 for a new record, otherwise 1. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - initial - 0 - any float - Starting peak, and the peak 'reset' returns to. ``.poltocar`` ------------- Converts a polar point, a distance from the origin and an angle in radians, to its x and y coordinates. The inverse of .cartopol. :Kind: Control-rate Both outlets send on every calculation, y first, so an object that takes both values already has y when x arrives. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - amplitude - FLOAT, INT - any float - Distance from the origin; sends the result. * - 1 - angle - FLOAT, INT - any float - Angle in radians from the positive x axis, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - x - FLOAT - any float - x coordinate of the point. Sent after y. * - 1 - y - FLOAT - any float - y coordinate of the point. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - angle - 0 - any float - Starting angle in radians. ``.pong`` --------- Keeps a number inside the range low to high by folding it back from the limits, the default, by wrapping it around to the other side, or by clipping it. Sends the result as a float. :Kind: Control-rate **Modes** The third argument sets the mode: - 3, fold (the default): a number past a limit is reflected back, as many times as needed. With the range 0 to 10, 12 gives 8 and -3 gives 3. - 2, wrap: a number past a limit comes back in from the other side. The range includes ``low`` but not ``high``, so 10 gives 0, 12 gives 2 and -3 gives 7. Fed from a counter, this cycles through the range, negative counts included. - 1, clip: as ``.clip``. - 0: the number passes unchanged. Any other mode folds. The limits may be given in either order, and when they are equal the result is always that value. An infinity goes to the nearest limit, and an undefined number (NaN) counts as 0. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - value - FLOAT, INT - any float - Number to keep in range; sends the result. * - 1 - low - FLOAT, INT - any float - Lower limit, stored for the next result. * - 2 - high - FLOAT, INT - any float - Upper limit, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - low to high - The number folded, wrapped or clipped into the range. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - low - -1 - any float - Lower limit. * - high - 1 - any float - Upper limit. * - mode - 3 - 0 to 3 - 0 passes numbers through, 1 clips, 2 wraps, 3 folds. ``.pow`` -------- Raises the left operand to the power of the right one and sends the result as a float. Combinations with no finite real result, such as a negative base with a fractional exponent, send 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - base - FLOAT, INT - any float - Base; sends the result. * - 1 - exponent - FLOAT, INT - any float - Exponent, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - base to the power of exponent, or 0 when that has no finite value. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - exponent - 0 - any float - Starting exponent. ``.round`` ---------- Rounds a number to the nearest multiple of the step and sends it as a float: a step of 1, the default, rounds to whole numbers and 0.5 to halves. Halfway values round away from zero; a step of 0 passes the number unchanged. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number to round; sends the result. * - 1 - step - FLOAT, INT - any float - Step to round to, stored for the next result. 0 turns rounding off. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The input rounded to the nearest multiple of the step. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - step - 1 - any float - Starting step. 0 passes numbers through unchanged. ``.scale`` ---------- Maps a number from the input range onto the output range and sends it as a float. An exponent other than 1 bends the mapping into a curve; numbers outside the input range map past the output range unless clip is 1. :Kind: Control-rate The mapping is .. code-block:: text n = (value - inLow) / (inHigh - inLow) out = outLow + (outHigh - outLow) * n ^ exponent so an exponent above 1 starts slowly and ends fast, and one below 1 does the opposite. Below ``inLow``, where n is negative, the curve is mirrored. .. code-block:: text [.scale 0 127 0 1] 64 => 0.504 [.scale 0 127 0 1 2] 64 => 0.254 A number outside the input range maps past the output range. Set the sixth argument, ``clip``, to 1 to limit the result to the output range instead, or use ``.zmap``, which always limits and is always a straight line. Either range may run from high to low. When ``inLow`` equals ``inHigh``, the result is ``outLow``. A result that is not a finite number sends 0. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - value - FLOAT, INT - any float - Number to map; sends the result. * - 1 - inLow - FLOAT, INT - any float - Input value that maps to outLow, stored for the next result. * - 2 - inHigh - FLOAT, INT - any float - Input value that maps to outHigh, stored for the next result. * - 3 - outLow - FLOAT, INT - any float - Output for inLow, stored for the next result. * - 4 - outHigh - FLOAT, INT - any float - Output for inHigh, stored for the next result. * - 5 - exponent - FLOAT, INT - any float - Curve exponent, stored for the next result. 1 is a straight line. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The number mapped onto the output range. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - inLow - 0 - any float - Input value that maps to outLow. * - inHigh - 127 - any float - Input value that maps to outHigh. * - outLow - 0 - any float - Output for inLow. * - outHigh - 1 - any float - Output for inHigh. * - exponent - 1 - any float - Curve exponent; 1 is a straight line. * - clip - 0 - 0 or 1 - 1 limits the result to the output range; 0 lets numbers outside the input range map past it. ``.sin`` -------- Sends the sine of an angle in radians, as a float. :Kind: Control-rate **The single-input functions** ``.sin``, ``.cos``, ``.tan``, ``.asin``, ``.acos``, ``.atan``, ``.sinh``, ``.cosh``, ``.tanh``, ``.asinh``, ``.acosh``, ``.atanh``, ``.abs`` and ``.sqrt`` have one inlet. A number there, int or float, sends the result at once as a float. Angles are in radians: a full circle is 2 pi, about 6.2832. To use degrees, multiply by 0.017453 (pi / 180) first: .. code-block:: text [.* 0.017453] -> [.sin] 90 => 1 Where a function has no finite result, for a number outside its range or a result too large for a float, it sends 0. When 0 is also a meaningful result, check the range of the input first. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float (radians) - Angle in radians; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - -1.0 to 1.0 - The sine of the input. ``.sinh`` --------- Sends the hyperbolic sine of a number. Beyond about -89 and 89 the result is too large for a float, and 0 is sent. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The hyperbolic sine of the input. ``.slide`` ---------- Smooths a stream of numbers. Each number moves the output part of the way towards it: 1/slideUp of the distance when rising, 1/slideDown when falling. A slide of 1 passes numbers straight through. :Kind: Control-rate Each number moves the output ``(number - output) / slide`` closer to it. A slide of 1 jumps straight to the number; a slide of 10 covers a tenth of the remaining distance per number. The output starts at 0. .. code-block:: text [.slide 4 4] 100, 100, 100 => 25, 43.75, 57.81 The smoothing counts numbers, not time, so it depends on how often numbers arrive. For a ramp over a set time, use ``.line`` or ``~line``. A slide below 1 counts as 1. Once the output is within a millionth of the number, it lands exactly on it. An infinite or undefined number (NaN) counts as 0. **Messages** - bang: take another step towards the last number. Repeated bangs glide the output to it. - ``set ``: make n the number to move towards, without sending. Follow it with bangs. - ``reset``: set the output to 0 without sending. The number to move towards is kept. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - value - FLOAT, INT, BANG, LIST - any float - Number: take one step towards it and send the output. Bang: take another step towards the last number. 'set ': set the target without sending. 'reset': set the output to 0 without sending. * - 1 - slideUp - FLOAT, INT - 1+ - Slide used while the output rises. Below 1 counts as 1. * - 2 - slideDown - FLOAT, INT - 1+ - Slide used while the output falls. Below 1 counts as 1. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - between the previous output and the input - The smoothed value. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - slideUp - 1 - 1+ - Starting slide while rising. Below 1 counts as 1. * - slideDown - 1 - 1+ - Starting slide while falling. Below 1 counts as 1. ``.sqrt`` --------- Sends the square root of a number, as a float. A negative number sends 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number; sends the result. A negative number sends 0. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - 0 or higher - The square root of the input, or 0 when the input is negative. ``.swap`` --------- Sends two numbers out in swapped order. A number on the left inlet leaves the right outlet, then the number stored on the right inlet leaves the left outlet. :Kind: Control-rate Use it when two values arrive in the wrong order for the hot and cold rule (see ``.+``). The right outlet always sends first, and everything connected to it finishes before the left outlet sends, so wire the right outlet to a cold inlet and the left outlet to the hot one: .. code-block:: text [.swap 100] right outlet -> right inlet of [.-] left outlet -> left inlet of [.-] x -> left inlet of [.swap] => [.-] sends 100 - x Each number keeps its type: an int leaves as an int and a float as a float. The argument's spelling sets its type: ``.swap 5`` holds the int 5 and ``.swap 5.`` the float 5. **Messages** - a number on the left inlet: store it and send the pair. - bang: send the pair again unchanged. Before anything has arrived, that is 0 and the argument. - a list: the first number goes to the left inlet's slot and the second to the right's, then the pair is sent. A single number leaves the right slot alone. Reading stops at the first word, and a list that starts with a word is ignored. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT, BANG, LIST - any number - Number: store it and send the pair. Bang: send the pair again. List of two numbers: store both and send. Leaves on the right outlet. * - 1 - right - FLOAT, INT - any number - Number for the left outlet, stored without sending. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - fromRight - ANY - any number - The number from the right inlet, as the int or float it arrived as. Sent second. * - 1 - fromLeft - ANY - any number - The number from the left inlet, as the int or float it arrived as. Sent first. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any number - Starting number for the left outlet. Written as 5 it is an int; written as 5. or 5e0 it is a float. ``.tan`` -------- Sends the tangent of an angle in radians, as a float. Where the result would be infinite, it sends 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float (radians) - Angle in radians; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The tangent of the input. ``.tanh`` --------- Sends the hyperbolic tangent of a number: a smooth S-curve between -1 and 1, often used for soft saturation. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT - any float - Number; sends the result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - -1.0 to 1.0 - The hyperbolic tangent of the input. ``.togedge`` ------------ Bangs the left outlet when a value becomes non-zero and the right outlet when it returns to 0, and stays silent in between. A bang flips the value between zero and non-zero. :Kind: Control-rate Only transitions are reported: 5 followed by 9 sends nothing, and neither does 0 followed by 0. The two outlets therefore take turns, never banging twice in a row from the same side, which makes them a reliable pair of note-on and note-off triggers. .. code-block:: text 0, 0.2, 0.8, 0.3, 0 => left bang at 0.2, right bang at the last 0 The value starts at 0, so the first non-zero number bangs the left outlet and a first 0 sends nothing. Any number other than 0 counts, fractions such as 0.5 included. **Messages** - bang: flip the value between zero and non-zero, and bang the matching outlet. A stream of bangs alternates left, right, left. After a number such as 5, a bang flips to 0 and bangs the right outlet. - ``reset``: set the value to 0 without sending, so the gate is closed again without a right-outlet bang. A list counts as its first number. Words and infinite or undefined numbers (NaN) are ignored. ``.change`` reports the same transitions as 1s, next to the value. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any float - Number to watch. Bang: flip between zero and non-zero, and report it. 'reset': set the value to 0 without sending. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - rising - BANG - bang - Bang when the value changes from 0 to non-zero. * - 1 - falling - BANG - bang - Bang when the value changes from non-zero to 0. ``.trough`` ----------- Keeps the smallest number received so far and sends it only when a new number goes below it. Two more outlets report whether each number set a new minimum. :Kind: Control-rate Works like ``.peak`` with the comparison reversed: a number below the minimum becomes the new minimum and is sent. The minimum starts at 128, so MIDI values can go below it. For larger data, give a higher start, such as ``.trough 100000``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - FLOAT, INT, BANG, LIST - any float - Number: send it if it is below the minimum. Bang: send the minimum. List ' ': set the minimum, then offer the number. 'set ': set the minimum without sending. 'reset': go back to the starting minimum without sending. * - 1 - seed - FLOAT, INT - any float - Number that becomes the new minimum and is sent, always reported as a new record. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The new minimum. Silent when a number does not go below it. * - 1 - new - INT - 0 or 1 - 1 when the number just received set a new record, otherwise 0. * - 2 - same - INT - 0 or 1 - The opposite of the 'new' outlet: 0 for a new record, otherwise 1. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - initial - 128 - any float - Starting minimum, and the minimum 'reset' returns to. 128 by default, so that ordinary numbers can go below it. ``.vexpr`` ---------- Evaluates an expression for every item of a list, as .expr does for single numbers, and sends the results as a list. A single number on an inlet is used for every item. :Kind: Control-rate The language is that of ``.expr``: placeholders, operators, types, functions and errors work as described there. Every inlet holds a list, and a single number is a one-item list. The expression runs once per position, up to the length of the shortest list among the inlets it uses. An inlet that holds one item supplies it to every position. .. code-block:: text [.vexpr $f1 * $f2] 0.5 -> right inlet, then 60 64 67 -> left => 30 32 33.5 [.vexpr $i1 + $i2] 0 4 7 -> right inlet, then 60 -> left => 60 64 67 A single result leaves as an int or a float rather than a list. Every inlet takes lists, of up to 256 items; items past that are dropped. A list without numbers is ignored, a bang calculates again, and an inlet that has received nothing reads as a single 0. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - $1 - FLOAT, INT, BANG, LIST - any list of floats - List for $i1 and $f1; sends the results. A single number counts as a one-item list. Bang: calculate again. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - ANY - any list of floats - One result per item, as a list; a single result as an int or a float. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - expression - — - any expression - The expression to evaluate for every item, for example "$f1 * $f2". Its placeholders decide how many inlets there are. ``.zmap`` --------- Maps a number from the input range onto the output range, in a straight line, and sends it as a float. A number outside the input range gives the nearest output limit, so the result never leaves the output range. :Kind: Control-rate The mapping is the straight-line ``.scale``, always limited to the output range. A number outside the input range, an infinity included, gives the nearest output limit: .. code-block:: text [.zmap 0 127 0 1] 200 => 1 -5 => 0 Either range may run from high to low. When ``inLow`` equals ``inHigh``, the result is ``outLow``. The inlets work as described under ``.+``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - value - FLOAT, INT - any float - Number to map; sends the result. * - 1 - inLow - FLOAT, INT - any float - Input value that maps to outLow, stored for the next result. * - 2 - inHigh - FLOAT, INT - any float - Input value that maps to outHigh, stored for the next result. * - 3 - outLow - FLOAT, INT - any float - Output for inLow, stored for the next result. * - 4 - outHigh - FLOAT, INT - any float - Output for inHigh, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - FLOAT - any float - The number mapped onto the output range, limited to it. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - inLow - 0 - any float - Input value that maps to outLow. * - inHigh - 127 - any float - Input value that maps to outHigh. * - outLow - 0 - any float - Output for inLow. * - outHigh - 1 - any float - Output for inHigh. ``.|`` ------ Bitwise OR of two integers, sent as an int. Floats are truncated toward zero first. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any int - Left operand; sends the result. Floats are truncated toward zero. * - 1 - right - FLOAT, INT - any int - Right operand, stored for the next result. Floats are truncated toward zero. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - any int - The bitwise OR of both operands. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any int - Starting right operand. ``.||`` ------- Logical OR: sends 1 when either operand is non-zero, otherwise 0. :Kind: Control-rate **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - FLOAT, INT - any float - Left operand; sends the result. * - 1 - right - FLOAT, INT - any float - Right operand, stored for the next result. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - INT - 0 or 1 - 1 when either operand is non-zero, 0 otherwise. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Starting right operand. ``~*`` ------ Multiplies an audio signal by another audio signal or by a float: a gain stage, or a ring modulator. :Kind: DSP (audio-rate) **The audio-rate operators** ``~+``, ``~-``, ``~*`` and ``~/`` share these rules: - The left inlet takes the audio signal. Nothing comes out while no audio reaches it. - The right inlet takes an audio signal or a number, int or float. While audio is connected there, it is used sample by sample; otherwise the last number is used, or the argument until a number arrives. - A new number takes effect at the next audio block and is not smoothed, so a large jump can click. Ramp it with ``~line`` instead. - When no argument is given, ``~+`` and ``~-`` use 0 and ``~*`` and ``~/`` use 1, so a bare object passes the signal through unchanged. .. code-block:: text [~* 0.5] halves the signal's level **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - BUFFER - any float - Audio signal. * - 1 - right - BUFFER, FLOAT, INT - any float - Audio signal, or a number used while no audio is connected. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - BUFFER - any float - left * right. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 1.0 - any float - Float used while no audio is connected to the right inlet. ``~+`` ------ Adds two audio signals, or adds a float to an audio signal. :Kind: DSP (audio-rate) **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - BUFFER - any float - Audio signal. * - 1 - right - BUFFER, FLOAT, INT - any float - Audio signal, or a number used while no audio is connected. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - BUFFER - any float - left + right. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Float used while no audio is connected to the right inlet. ``~-`` ------ Subtracts an audio signal, or a float, from an audio signal. :Kind: DSP (audio-rate) **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - BUFFER - any float - Audio signal. * - 1 - right - BUFFER, FLOAT, INT - any float - Audio signal, or a number used while no audio is connected. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - BUFFER - any float - left - right. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 0 - any float - Float used while no audio is connected to the right inlet. ``~/`` ------ Divides an audio signal by another audio signal or by a float. A float of 0 leaves the signal unchanged. :Kind: DSP (audio-rate) A number of 0 on the right inlet leaves the signal unchanged. An audio divisor that reaches 0 produces infinite samples, so keep it away from 0. The other rules are described under ``~*``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - left - BUFFER - any float - Audio signal. * - 1 - right - BUFFER, FLOAT, INT - any non-zero float - Audio signal, or a number used while no audio is connected. A number of 0 leaves the signal unchanged. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - BUFFER - any float - left / right. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - right - 1.0 - any non-zero float - Float used while no audio is connected to the right inlet. 0 leaves the signal unchanged. ``~clip`` --------- Hard clipper: limits every sample of an audio signal to the range low to high. Use it to tame stray peaks, or as a distortion stage. :Kind: DSP (audio-rate) The low and high inlets take ints and floats. When low is above high, every sample becomes high. New limits take effect at the next audio block. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - in - BUFFER - any float - Audio signal. * - 1 - low - FLOAT, INT - any float - Lower limit, as an int or a float. * - 2 - high - FLOAT, INT - any float - Upper limit, as an int or a float. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - BUFFER - low to high - The signal limited to low to high. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - low - -1.0 - any float - Starting lower limit. * - high - 1.0 - any float - Starting upper limit.