Search by

train-horn / yii2-sound-level

trainhorn

Yii 2 extension: sound pressure level at distance (inverse-square law with optional air absorption), level addition, an accessible table widget and a console command.

Package info

github.com/train-horn/yii2-sound-level

Homepage

Type:yii2-extension

pkg:composer/train-horn/yii2-sound-level

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-19 00:58 UTC

This package is not auto-updated.

Last update: 2026-11-19 19:59:35 UTC


README

A Yii 2 extension that estimates sound pressure level (SPL) at a distance from a level known at a reference distance, e.g. "150 dB at 10 ft". It uses the free-field inverse-square law with an optional air-absorption term, and can add levels from several sources.

It is a PHP port of the calculator behind the Train Horn decibel-at-distance tool, with the same formulas and the same test vectors. Maintained by Train Horn, an independent reference on train horns.

What you get:

  • SoundLevel: an application component (level at distance, inverse, level addition, distance-ratio loss).
  • SoundLevelTable: a widget that renders an accessible HTML table for a list of distances.
  • sound-level: a console command, e.g. yii sound-level/table 150 10.

Installation

composer require train-horn/yii2-sound-level

Requires PHP 7.4+ and Yii 2.0.45+. Tested with PHP 8.5 and Yii 2.0.55.

The model

L(d) = L_ref - 20 * log10(d / d_ref) - alpha * (d - d_ref) / 1000
  • L_ref: level in dB at the reference distance d_ref (ratings are often quoted "at 10 ft" or "at 1 m").
  • alpha: optional air absorption in dB/km, applied to the extra path (distances converted to metres). Default 0.
  • Each doubling of distance costs about 6.02 dB; ten times the distance costs 20 dB.
  • Incoherent sources add as 10 * log10(sum(10^(L_i/10))), so two equal horns add about 3 dB.

SoundLevel::AIR_ABSORPTION_DB_PER_KM holds rounded typical values by octave band (10 degC, 70 % RH, after ISO 9613-1/9613-2). For horn frequencies (about 250-600 Hz) absorption is only 1-2 dB/km, so it matters only at long range.

Limits: free field only. Ground reflection, barriers, wind and temperature gradients are ignored, and the law does not hold very close to the source. The results are estimates, not measurements, and not a legal noise assessment.

Component

// config/web.php or config/console.php
'components' => [
    'soundLevel' => [
        'class' => \trainhorn\soundlevel\SoundLevel::class,
        'refDistance' => 10,      // default reference distance
        'unit' => 'ft',           // 'ft' or 'm'
        'absorptionDbPerKm' => 0, // 0 = pure inverse-square law
    ],
],
$spl = Yii::$app->soundLevel;

$spl->splAtDistance(150, 100);              // 130.0  (150 dB at 10 ft -> 100 ft)
$spl->splAtDistance(120, 10, 1, 'm');       // 100.0  (120 dB at 1 m -> 10 m)
$spl->splAtDistance(150, 1010, 10, 'm', 2); // 107.91 (with 2 dB/km absorption)
$spl->distanceForSpl(150, 90);              // 10000.0 ft
$spl->combineLevels([100, 100]);            // 103.01
$spl->doublingLoss();                       // 6.02
$spl->table(150, [10, 100, 1000]);          // [['distance' => 10.0, 'level' => 150.0], ...]

Every argument after the first two is optional and falls back to the component defaults. Invalid input (non-numeric, NaN/INF, distance <= 0, negative absorption, unknown unit) throws trainhorn\soundlevel\InvalidInputException, a subclass of yii\base\InvalidArgumentException.

Widget

use trainhorn\soundlevel\widgets\SoundLevelTable;

echo SoundLevelTable::widget([
    'sourceDb' => 150,
    'refDistance' => 10,
    'unit' => 'ft',
    'distances' => [10, 50, 100, 500, 1000],
    // 'absorptionDbPerKm' => 1.9,
    // 'calculator' => 'soundLevel',   // use the configured component's defaults
    // 'caption' => 'Horn A',
    // 'options' => ['class' => 'table table-sm'],
]);

The table has a <caption>, column headers with scope="col" and one row header with scope="row" per distance, so screen readers read each level together with its distance.

Console command

The extension registers the sound-level command in console applications automatically (Composer extra.bootstrap). To register it by hand: 'controllerMap' => ['sound-level' => \trainhorn\soundlevel\console\SoundLevelController::class].

$ ./yii sound-level/table 150 10
Distance (ft)  Level (dB)
10                  150.0
25                  142.0
50                  136.0
100                 130.0
250                 122.0
500                 116.0
1000                110.0
2500                102.0
5000                 96.0
Free-field estimate, not a measurement.

$ ./yii sound-level/table 120 1 --unit=m --distances=1,10,100,1000 --absorption=1.9
$ ./yii sound-level/at 150 100          # 130.0 dB
$ ./yii sound-level/distance 150 90     # 10000 ft
$ ./yii sound-level/combine 100,100     # 103.0 dB

Invalid input prints an error to stderr and exits with code 65 (ExitCode::DATAERR).

Tests

composer install
vendor/bin/phpunit

40 tests cover the known values (150 dB at 10 ft gives 130.0 dB at 100 ft), round trips with and without absorption, level addition, the widget markup, the console command and invalid input.

License

MIT. See LICENSE.