Legacy Script V1.0 References

This page is about the structure of old script version of Usine HH4 and HH3
For Usine HH5 and higher use this page.

Scructure of a script

init

This procedure is called when the script is compiled or loaded. It's the place where you initialize inlets/outlet or any variable.

procedure Init;
begin
  // Initialisation code
 input := CreateParam('input',ptDatafader);
 SetIsOutput(input,false);
 SetMin(input,0);
 SetMax(input,100);
 SetSymbol(input,'%');
 SetDefaultValue(input,10);
 SetValue(input,10);  
end;

destroy

This procedure is called when the script is destroyed.

Inlets/outlet are destroyed automatically so you mustn't destroy them in the Descroy bloc.

procedure Destroy;
begin
  MyStringList.free;
  SetLength(MyArray,0);
end;

process

This procedure is called on each execution bloc (around 3ms with a normal setup). It's the place where you generally do the calculation.

procedure Process;
begin
  inval := getValue(input);
  setvalue(output,inval);     
end;

callback

This procedure is called each time an inlet is modified. The N parameter is the index of the modified inlet.

That allows an optimisation over constant running Process procedure: the code will run only if input changed.

The Callback will scan the inputs from 0 to n and can trigg a specific code when input change is detected.

So if results are supposed to be computed only when input changed, prefer the callback to the process procedure.

However if things need computations at a different bloc time that input changed, still need the process procedure.

For exemple an input change can set to 1 a parameter in callback, but if wanna set this param back to 0 next bloc, (like a 'has chg' behaviour) the code to set back to 0 will occur in Process Procedure, unless it's trigg by an input.

You can use either Callback or Process Procedure, or booth simultaneously

according to needs.

The callback is provided at messages rate, typically every 25 or 50ms depending on the setup refresh speed.

To ensure a faster callback (immediately after the inlet has been modified) use the SetFastCallBack procedure describe bellow.

procedure Init;
begin
// Initialisation of a fast callback inlet
input := CreateParam('input',ptDatafader);
SetFastCallBack(input,true);
end;
procedure Callback(N:integer);
begin
  inval := getValue(input);
  setvalue(output,inval);     
end;

processIDLE

This procedure is called at the setup refresh speed (around 25ms or 50ms). It's the place where you do calculation which doesn't need a fast speed, IML or graphic stuffs like SendInternalMsg (see bellow).

procedure ProcessIDLE;
begin
  inval := getValue(input);
  setvalue(output,inval);     
end;

Declarations

constants

  BlocSize      // size of Usine audio blocs
  BlocDuration  // duration of a bloc calculation according to the sampling rate
  RefreshSpeed  // refresh speed in mS as defined in the setup (v5.5 and above)
  SamplingRate  // current audio sampling rate

trace Values

  procedure sTrace(S:string); 
  procedure iTrace(I:Integer); 
  procedure fTrace(F:single); 

modules Settings

  Procedure SetModuleColor(Color:integer); // set the color of the module
                                           // as it is displayed in the patch
                                           // Usine 5.50 and above

parameters

  Type TParameter;
  Type TAlphaColor;
  type TScale     = (
                    lsLinear,
                    lsLog,
                    lsExp
                    );
  type TParamType = (
                     ptTextField,     // text in/outlet
                     ptColor,         // color in/outlet
                     ptMIDI,          // MIDI in/outlet
                     ptGainFader,     // gain fader -84 to +12 dB in/outlet
                     ptAudio,         // audio in/outlet
                     ptDataField,     // float or integer in/outlet without mouse fader (click to edit value)
                     ptDataFader,     // float or integer in/outlet with mouse fader (use the mouse to modify)
                     ptButton,        // button (trigger) in/outlet
                     ptListBox,       // combobox box in/outlet use SetListBoxString to set items
                     ptSwitch,        // switch in/outlet
                     ptArray,         // array in/outlet
                     ptIpAddress,     // data with the format xxx.xxx.xxx.xxx in/outlet suitable for IP addresses
                     ptTimecode,      // data with the format  HH:MM:SS:FF in/outlet suitable for Timecode
                     ptMIDINoteFader, // midi note in the range 0..127 displayed as MIDI notes ie. 36-C1
                     ptPointerBitMap, // general bitmap pointer in/outlet in hexadecimal
                     ptPointer,       // general pointer in/outlet in hexadecimal
                     ptLed,           // equivalent to ptSwitch with a left led layout
                     ptChooseFolder,  // open folder in/outlet
                     ptRightLed,      // equivalent to ptSwitch with a right left led layout
                     ptTriggerLed,    // equivalent to ptSwitch with a left led type layout 
                     ptFileName       // open a file name in/outlet
                     );

  type  TMIDI = Record
         Msg   : Byte;
         Data1 : Byte;
         Data2 : Byte;
         Channel : byte;
        end;

see midi-implementation

  function CreateParam    (caption: string; typ: TParamType):TParameter; // Create a new parameter, 
                                                                         // returns the parameter's number

  procedure SetIsInput      (Param: TParameter; val: boolean);   // set to true if the parameter has input port
  procedure SetIsOutput     (Param: TParameter; val: boolean);   // set to true if the parameter has output port
  procedure SetScale          (Param: TParameter; val: TScale);    // set the scale, if the param is a fader
  procedure SetColor          (Param: TParameter; val: integer);   // set the front color of the fader 
                                                                 // or ON Color for switches
  procedure SetVisible      (N : Tparameter; val: Boolean);      // determines if the parameter is visible, 
                                                                 // true by default
  procedure SetOffColor     (Param: TParameter; val: integer);   // set the off color only if the parameter is a 
                                                                 // switch
  procedure SetMin           (Param: TParameter; val: single);   // set min parameter value
  procedure SetMax           (Param: TParameter; val: single);   // set max parameter value
  procedure SetMinMaxNoLimit (Param: TParameter);                // the parameter's value is not limited

  procedure SetDefaultValue  (Param: TParameter; val: single);   // set default param value, when created
  procedure SetCaption       (Param: TParameter; val: string);   // set or change displayed caption 
  procedure SetSymbol          (Param: TParameter; val: string);   // set displayed symbol ie. 'ms','%'
  procedure SetFormat          (Param: TParameter; val: string);   // set format string of the displayed value 
                                                                 // ie. '%g','%.0f','%.1f'
  procedure SetListBoxString (Param: TParameter; val: string);   // set listbox items ie.'"item1","item2"'
  procedure SetReadOnly      (Param: TParameter; val: boolean);  // set to true if the user can't modify value
  procedure SetFastCallBack  (Param: TParameter; val: boolean);  // set to true to use a fast callback insteed the
                                                                 // Windows message processing 
  procedure SetDontSave      (Param: TParameter; val: boolean);  // specifies if the parameter need to be save 
                                                                 // in the patch or not
  procedure SetSavedName     (Param: TParameter; val: string);   // set name which will be used to store the value
                                                                 // by default value are stored according 
                                                                 // their caption
  procedure SetIsSeparator   (Param: TParameter; val: boolean);  // determines if the parameter is followed by a 
                                                                 // blank line in the module panel

Access to Parameter's Value

  procedure SetStringValue   (Param: TParameter; val: string);   // set text value if param type = ptTextField
  function  GetStringValue   (Param: TParameter;) : string;      // get text value if param type = ptTextField

  procedure SetLength        (Param:   TParameter; val: integer);
  function  GetLength        (Param:   TParameter):integer;

  procedure SetValue         (Param:   TParameter; val: single);
  function  GetValue         (Param:   TParameter):single;  

  procedure SetDataArrayValue(Param: TParameter; I: integer; val: single);
  function  GetDataArrayValue(Param: TParameter; I: intege):single;

  procedure SetMIDIArrayValue(Param : TParameter; I: integer; val: TMIDI);
  procedure GetMIDIArrayValue(Param : TParameter; I: integer; var val:TMIDI);

  procedure SetColorArrayValue  (Param : TParameter;I: integer; val: TAlphaColor);
  function  GetColorArrayValue  (Param : TParameter;I: integer): TAlphaColor;

  function  GetDataPointer   (Param:   TParameter):PSingle;

Timecode and Markers Position.

  function GetTimecodePos:double;
  procedure SetTimecodePos (pos:double);
  function GetLoopMarkerPos (N:integer):double; // N from 0 to nbMarkers-1

dynamic Array's or String Length Manipulation

  function getarraylength (arr :array: integer;
  procedure setarraylength(arr :array; len:integer);

usine Internal Messages (IML)

  SendUsineMsg (msg:string);  
  SendInternalMsg1(msg:string); 
  SendInternalMsg2(msg,arg1:string);
  SendInternalMsg3(msg,arg1,arg2:string);
  SendInternalMsg4(msg,arg1,arg2,arg3:string);
  SendInternalMsg5(msg,arg1,arg2,arg3,arg4:string);   
  SendInternalMsg6(msg,arg1,arg2,arg3,arg4,arg6:string);

  function GetVariableString(name:string):string;
  function GetVariableInteger(name:string):integer;
  function GetVariableFloat(name:string):double;

The SendInternalMsg script command should not be executed in the process procedure context.

You can use safely it in the processIDLE procedure.

In the callback procedure set SetFastCallBack(MyIMLTriggeringInputParameter, false); to asynchronously execute the callback function that contains the SendInternalMsg calls in the Usine IDLE processing thread instead of the process thread. Otherwise IML calls might lead to undefined behaviour (function might not be executed, Usine crashes, etc.))

examples
  SendInternalMsg2('SET-TARGET-PATCH','SENDER-PATCH');
  SendInternalMsg4 ('GET-VALUE',GetStringValue(Input1),GetStringValue(Input2),'THEPARAMVALUE');
  SendInternalMsg3 ('SET-VALUE','PARAM','1','THEPARAMVALUE');
  SendInternalMsg4('SET-VALUE',GetStringValue(Input1),GetStringValue(Input2),FloatTostr(GetValue(Input3)));

stringList

  function TStringList.create:TStringList; 
  function TStringList.GetCommaText:String;
  procedure TStringList.SetCommaText(Comma:string);
  procedure TStringList.Sort;
  procedure TStringList.SaveToFile(FileName:string);   // If no path is specified for the file; will default to the last location saved/opened in Usine. 
  procedure TStringList.LoadFromFile(FileName:string); // If no path is specified for the file; will default to the last location saved/opened in Usine.
  procedure TStringList.clear;
  procedure TStringList.free;
  function TStringList.getstrings(i:integer):String;
  procedure TStringList.setstrings(i:integer;value:String);
  procedure TStringList.add(value:String);
  procedure TStringList.delete(index:integer);
  function TStringList.indexOf(value:string):integer;
  function TStringList.count:integer;
  function TStringList.Getcount:integer;

math

  Function minS(const A,B:single):Single;
  Function MaxS(const A,B: Single): Single;
  Function maxI(const A,B:integer):integer;
  Function minI(const A,B:integer):integer;

  Function Pi   : Extended;
  Function Log  (e: Extended) : Extended;
  Function Exp  (e: Extended) : Extended;) : Extended;
  Function Arctan   (e: Extended) : Extended;
  Function Arcsin   (e: Extended) : Extended;
  Function Arccos   (e: Extended) : Extended;
  function Abs(d: Extended): Extended;
  function Abs(d: Int64): Int64;
  function Power(Base, Exponent: Extended): Extended;
  function Sqr(d: Extended): Extended;
  function Sqrt(d: Extended): Extended;
  function ArcTan(d: Extended): Extended;
  function Ln(d: Extended): Extended;
  function Sin(d: Extended): Extended;
  function Cos(d: Extended): Extended;
  function Exp(d: Extended): Extended;
  function Round(d: Extended): Int64;
  function Round(d: Extended; Precision: Int8): Extended;
  function Frac(d: Extended): Extended;
  function Int(d: Extended): Extended;
  function Trunc(d: Extended): Int64;
  function Ceil(d: Extended): Int64;
  function Floor(d: Extended): Int64;

  function Random(Min, Max: Int64): Int64;
  function Random(l: Int64): Int64;
  function Random: Extended;
  procedure Randomize;

date and Time


var
  HoursPerDay,
  MinsPerHour,
  SecsPerMin,
  MSecsPerSec,
  MinsPerDay,
  SecsPerDay,
  MSecsPerDay,
  DateDelta;

type
  TDateTime : double;
  TTime : double;

  function EncodeDate(Year, Month, Day: UInt16): TDateTime;
  function EncodeTime(Hour, Min, Sec, MSec: UInt16): TDateTime;
  procedure DecodeDate(DateTime: TDateTime; var Year, Month, Day: UInt16);
  function DecodeDateFully(DateTime: TDateTime; var Year, Month, Day, DOW: UInt16): Boolean;
  procedure DecodeTime(DateTime: TDateTime; var Hour, Min, Sec, MSec: UInt16);

  function Date: TDateTime;
  function Time: TDateTime;
  function Now: TDateTime;

  function GetTickCount: UInt32;
  procedure Sleep(MilliSeconds: UInt32);

  procedure ReplaceTime(var DateTime: TDateTime; NewTime: TDateTime);
  procedure ReplaceDate(var DateTime: TDateTime; NewDate: TDateTime);

  function FormatDateTime(Format: string; DateTime: TDateTime): string;
  function StrToDate(s: string): TDateTime;
  function StrToDateDef(s: string; Default: TDateTime): TDateTime;
  function StrToTime(s: string): TDateTime;
  function StrToTimeDef(s: string; Default: TDateTime): TDateTime;
  function StrToDateTime(s: string): TDateTime;
  function StrToDateTimeDef(s: string; Default: TDateTime): TDateTime;

file names functions

  // File Names
  function  ExtractFileName(filename:String):string;
  function  ExtractFileDir(filename:String):string;
  function  ExtractFileExt(filename:String):string;
  function  SubFileExt(filename:String):string;
  function  PathDelim:string; // returns '/' on MACOS, '\' on windows
  procedure CreateDir(dir:String);
  function  GetApplicationPath:string; //give the absolute path of the current Usine's folder

strings

  type TTextLineBreakStyle  = (tlbsLF, tlbsCRLF, tlbsCR);
  type TReplaceFlags = set of (rfReplaceAll, rfIgnoreCase);

  function UpperCase(s: string): string;;
  function LowerCase(s: string): string;
  function UpCase(c: AnsiChar): AnsiChar;
  function UpCase(c: WideChar): WideChar;

  function CompareStr(s1, s2: string): Int32;
  function CompareMem(p1, p2: Pointer; Length: PtrUInt): EvalBool;
  function CompareText(s1, s2: string): Int32;
  function SameText(s1, s2: string): EvalBool;

  function  Copy (s: string; ifrom, icount: Longint): string;
  procedure Delete(var s: string; ifrom, icount: Longint);
  procedure Insert(s: string; var s2: string; ipos: Longint): string;
  function  StrGet(var S : String; i : Integer) : Char;
  procedure StrSet(c: Char; I : Integer; var s : String);
  function  Length(s: String) : Longint; 
  procedure SetLength(var S: String; L: Longint); 

  function AnsiUpperCase(s: string): string;
  function AnsiLowerCase(s: string): string;
  function AnsiCompareStr(s1, s2: string): Int32;
  function AnsiCompareText(s1, s2: string): Int32;
  function AnsiSameText(s1,s2:String): EvalBool;
  function AnsiSameStr(s1,s2:String): EvalBool;

  function Trim(s: string): string;
  function TrimLeft(s: string): string;
  function TrimRight(s: string): string;
  function PadL(s: string; Len: SizeInt; c: Char = '' ''): string;
  function PadR(s: string; Len: SizeInt; c: Char = '' ''): string;
  function Padz (s: string;I : longInt) : string; //  Is similar to Padl, but adds zeroes instead of spaces
  function QuotedStr(s: string): string;
  function AnsiQuotedStr(s: string; Quote: Char): string;
  function AnsiDequotedStr(s: string; AQuote: Char): string;

  function WrapText(Line, BreakStr: string; BreakChars: set of AnsiChar; MaxCol: Int32): string;
  function AdjustLineBreaks(s: string; Style: TTextLineBreakStyle): string;

  function IntToHex(Value: Int64; Digits: Int32 = 1): string;
  function IntToHex(Value: UInt64; Digits: Int32 = 1): string;
  function IntToStr(i: Int64): string; overload;
  function IntToStr(i: UInt64): string;
  function StrToInt(s: string): Int32;
  function StrToIntDef(s: string; Def: Int32): Int32;
  function StrToInt64(s: string): Int64;
  function StrToInt64Def(s: string; Def: Int64): Int64;
  function StrToUInt64(s: string): UInt64;
  function StrToUInt64Def(s: string; Def: UInt64): UInt64;
  function FloatToStr(f: Extended): string;
  function StrToFloat(s: string): Extended;
  function StrToFloatDef(s: string; Def: Extended): Extended;
  function CurrToStr(Value: Currency): string;
  function StrToCurr(s: string): Currency;
  function StrToCurrDef(s: string; Def: Currency): Currency;
  function StrToBool(s: string): EvalBool;
  function BoolToStr(B: EvalBool; TrueS: string = ''True''; FalseS: string = ''False''): string;
  function StrToBoolDef(s: string; Default: EvalBool): EvalBool;

  function Format(Fmt: string; Args: array of Variant): string;
  function FormatFloat(Format: string; Value: Extended): string;
  function FormatCurr(Format: string; Value: Currency): string;

  function LastDelimiter(Delimiters, s: string): SizeInt;
  function StringReplace(S, OldPattern, NewPattern: string; Flags: TReplaceFlags): string;
  Function IsDelimiter(Delimiters, s: string; Index: SizeInt): EvalBool;

  function Pos(Substr: string; Source: string): SizeInt;
  function StringOfChar(c: Char; l: SizeInt): string;
  function Replicate(c: char; I : longInt) : string; // Builds a string containing i times the character c

See also

version 6.0.241021

Edit All Pages