Safety | SuperCollider 3.13.0 Help

Description

Safety protects users from risky sound signals in two respects: It replaces bad values before they leave the software and enter the sound device, and it keeps the signal within +-1 (or a user-set lower limit) given by clipping, limiting, or other methods.

When the Safety quark is installed, it is on by default so that newbie users are safe; it can be turned off if desired. It puts itself at the tail of the rootnode; thus scope will be added after it, and master volume goes before it.

In ReplaceBadValues see esp. the method ugen.zap for suppressing bad numbers individually per synth.

First code examples:s.reboot; // Safety informs by posting: // -> Safety('localhost') is running, using 'safeClip_2' or similar. // Safety installs a Safety object for every known server: Safety.all; // which can be accessed in three ways: Safety(s); Safety(\localhost); Safety.all[\localhost]; // Safety reinstates protection when stopping all sounds with Cmd-Period: CmdPeriod.run; // -> posts Safety('localhost') etc // Safety can be disabled if desired: Safety(s).disable; Safety(s).enabled; s.queryAllNodes; // gone CmdPeriod.run; // -> no post after cmd-. // enable again Safety(s).enable; // posts Safety... again Safety(s).enabled; CmdPeriod.run; // posts s.queryAllNodes; // Setting the number of channels: // by default, a Safety has no numChannels value: Safety(s).numChannels // -> nil // then, it uses it's server's options.numOutputBusChannels // which is 2 by default s.options.numOutputBusChannels; // same as the "2" in "safeClip_2" CmdPeriod.run; // When you set a Safety's numChannels, these will be used: s.options.numOutputBusChannels = 8; CmdPeriod.run; // now uses "safeClip_8" // Choosing protection mode by setting defName // Safety has 4 modes in its synthDefFuncs dictionary: // \safeClip uses .clip(1.0) clipping // \safeSoft uses .softclip distortion // \safeTanh uses .tanh distortion // \safeLimit uses a Limiter.ar // you can add your own functions here: Safety.synthDefFuncs; // and change the defName like this: Safety(s).defName = \safeLimit; /// Set the general Safety limit level // - sets limit in all Safety objects: Safety.setLimit(0.8); Safety.limit; Safety(s).limit; // set individual limit for a Safety: Safety(\localhost).setLimit(0.5); // test that the set limit kicks in s.volume = -1; // play sound at full level +-1 { SinOsc.ar([220, 330]) }.play; s.plotTree; s.scope; // test setting general limit for all Safetys Safety.setLimit(0.2) // and individual limit for Safety(s) Safety(s).setLimit(0.8);

Class Methods

Safety.all

dict for all Safety objects

Safety.enable

Safety.disable

enable and disable all Safety objects at once

Safety.addServers

detect all present servers, and make Safety objects for them. When creating server by hand, run this method to use Safety on them too.

Safety.synthDefFuncs

dict for all synthDef-generating functions Safety can use

Safety.defaultDefName

Safety.defaultDefName = value

get and set the name the default synthdef to use

Safety.addSynthDefFunc(defName, func)

add a function to create a safety synthDef by name.

Safety.synthDefFor(defName, numChans: 2)

make a synthDef from a named synthDefFunc for a given number of channels

Safety.useRootNode

Safety.useRootNode = value

get and set whether to add safety synth to tail of rootnode or not. true by default. if false, safety synth will run after server.defaultGroup.

Safety.new(server, defName, enable: true, numChannels)

make a new Safety, needed only when creating a custom server.

Arguments:

server	the server for which to make the safety
defName	the name of the synthdef it should use
enable	flag whether to enable this safety when making it.
numChannels	sets number of output channels to protect by Safety. Only needed if different from s.options.numOutputBusChannels.

Inherited class methods

Undocumented class methods

Safety.classLimit

Safety.limit

Safety.setLimit(val: 1.0)

Instance Methods

.server

the server of this safety

.defName

.defName = name

get and set the name of the synthdef to use for this safety

.synth

the synth running for this safety

.treeFunc

the function in ServerTree used to send safety synth when booting or after cmd-period.

.numChannels

.numChannels = num

the number of output channels of safety.server

.enabled

flag whether this safety is enabled

.enable(remake: false)

.disable

enable and disable safety.

.asTarget

When Safety.useRootNode is true, this returns the server's rootnode; when false, it returns the server. This is used as target to whose tail the safety's synth will be added.

Inherited instance methods

Undocumented instance methods

.limit

.setLimit(val)

Examples

(
// example for adding a custom synthDefFunc:
// this one posts when Limiter goes into action.
// kindly contributed by Glen Fraser (@totalgee on GitHub)
Safety.addSynthDefFunc(\safeLimitNotify, { |numChans, limit=1|
    {
        var limitCtl = \limit.kr(limit).abs;
        var mainOuts = In.ar(0, numChans);
        var safeOuts = ReplaceBadValues.ar(mainOuts);
        var resetTrig = Impulse.ar(0.5);
        var peak = Peak.ar(safeOuts * (1 - resetTrig), resetTrig);
        var maxPeak = peak.reduce(\max);
        var delayMaxPeak = Delay1.ar(maxPeak);
        var overTrig = delayMaxPeak > limitCtl;
        var limited = Limiter.ar(safeOuts, limitCtl);
        (delayMaxPeak / limitCtl).ampdb.poll((delayMaxPeak > maxPeak) * overTrig, "Audio peak exceeded limit by dB");
        ReplaceOut.ar(0, limited);
    }
});
)

// tell all Safety objects to use it by default:
Safety.defaultDefName = \safeLimitNotify;

// Tests - see where Safety goes in the node tree :
s.boot;
s.plotTree;   // safety is there

// add a source
x = { RLPF.ar(Impulse.ar(300), \freq.kr(1000), 0.1, \amp.kr(0.1)) }.play;

// scope goes after safety:
s.scope;
// correct order: vol, safety, scope
s.volume.volume = -2;

/////////// TEST BAD SIGNALS:
x.set(\freq, -1.sqrt);  // signal gets bad -> mutes and posts info
x.set(\freq, 550);      // recovers

// try with second source
y = { SinOsc.ar([220, 330], 0, \amp.kr(0.1)) }.play;
x.set(\freq, -1.sqrt);  // signal on ch 1 goes bad -> silent, ch2 remains
x.set(\freq, 550);      // recovers
x.free; y.free;

/// test switching modes of volume limiting:
Safety(s).defName = \safeClip;
// remake scope to add it after safety,
// and set yZoom so you see the clip limit
s.scope(zoom: 1).yZoom_(0.9);
// make a sound with amp from 0 to 4
y = { SinOsc.ar([220, 330], 0, LFSaw.kr(0.3, 0, 2, 2)) }.play;
// test limiting: now with safeClip
y.set(\amp, 2); // gets clipped
y.set(\amp, 5); // gets clipped

Safety(s).defName = \safeSoft;
s.scope;
Safety(s).defName = \safeLimit;
s.scope;
Safety(s).defName = \safeTanh;
s.scope;
y.free;

// -------------- turn volume down on system output - gets softer

x.set(\freq, -1.sqrt);  // signal on ch 1 goes bad -> silent, ch2 remains
x.set(\freq, 550);      // recovers
x.set(\amp, 5); // gets limited
x.set(\amp, 0.5); // fine again
Safety(s).setLimit(0.5); // set limit lower
x.set(\amp, 5); // gets limited at 0.5;
x.set(\amp, 0.5); // fine again

// when multiple clients play on the same server,
// it may be preferable that each client runs a separate Safety
// on her own defaultGroup rather than on the shared RootNode:
// set flag
Safety.useRootNode = false;
Safety(s).disable; // turn it off and on again,
Safety(s).enable(true);
// ... and now it run within the defaultGroup:
s.plotTree;

// adding a custom Safety synthDefFunc:
// this one uses fold2, which distorts quite dramatically:

Safety.addSynthDefFunc(\mySafeFold, { |numChans|
    { |limit=1|
        // read the hardware output channel busses:
        var mainOuts = In.ar(0, numChans);
        // filter them for bad values
        var safeOuts = ReplaceBadValues.ar(mainOuts);
        // apply whatever custom limiting method
        var limited = safeOuts.fold2(limit);
        // write the safe and limited back to the output channels busses:
        ReplaceOut.ar(0, limited);
    }
});

Safety(s).defName_(\mySafeFold);
// and back to harmless limiter
Safety(s).defName_(\safeLimit);

helpfile source: /home/bgola/.local/share/SuperCollider/downloaded-quarks/SafetyNet/HelpSource/Classes/Safety.schelp
link::Classes/Safety::

Safety : Object Extension