gain

Builtin index · Signal processing

result = gain(x, db)

Input: x, db · Output: result

What it is

x: a number, vector, matrix or Signal; db: a number of decibels, also nameable (gain(x, db = -3)) and accepting a dB-suffixed literal (gain(x, -3 dB), since dB passes through dimensionless).

Overloads

One call shape — this function is not overloaded.

Examples

No documentation example calls this form yet. The Signal processing chapter is where one belongs.

How it works

gain(x, db) — scale a signal by a decibel amount, x * 10^(db/20). The AMPLITUDE/field-quantity convention, the same factor of 20 db2mag above uses and deliberately not the power one: a fader is the thing people reach for gain for, and a gain that quietly halved the dB scale would be wrong by 2x in dB for every one of them. (db vs. db_power immediately above is the same distinction, spelled out there at more length.) Shape-preserving through map1, like every other elementwise numeric builtin: a Signal comes back a Signal at the SAME fs — changing a level does not touch the time axis — a Vec stays a Vec, a Mat stays a Mat, a bare number just scales. gain(x, -3 dB) needs no special handling here. dB is a registered dimensionless unit passing through at factor 1.0 (see apply_unit), so a -3 dB literal reaches this arm already as -3 — probed 2026-09-18, type(-3 dB) is number. The amount is also nameable (gain(x, db = -3)) via the usual positional-or-named path, so the [db=] in the chapter is true rather than aspirational.

From the note above this builtin in the interpreter, where the reasoning was written down as it was built.