functions.js

A few basic functions to help with developing scripts for PreSonus Studio One 4.5+. The file is obfuscated and cannot be edited.

---

How To Use:

Right click the link and Save As... to download: functions.js
Copy it to your script project folder(s) and add include_file('functions.js') to the top of your JS code file.

There is error handling in the functions but if you encounter any errors with any function please leave a detailed comment here explaining the use so it can be trapped.

---

MESSAGING

• alert (value)
  Common alert box, string formatting is performed in the function

• print (value)
  Write to console, string formatting is performed in the function
  Outputs to the Studio One message window

---

TRACKS

• getTracks (selected [bool])
  Returns an array of arrange tracks
  Argument is optional: None or 0 = all tracks, 1 = selected tracks

• getTracksByName (string, [integer])
  Returns an array of tracks where the track name contains the string.
  Optional case sensitivy matching: 0 or none = no case sensitivity, 1 = case sensitive

• renameTracks (find [string], replace [string])
  Replace parts of all track names. Case sensitive matching (search string, replacment string)

• selectTrack (track [object])
  Use this to optionally select tracks when iterating when necessary

• setTrackColor (track [object], color [hex])
  Sets a track to a hex color, # char irrelevant

• getPan (track [object])
  Returns the pan value from a track's channel if any

• setPan (track [object], value [string])
  Sets the pan value for a track's channel if any setPan(track, 'L45')

---

CHANNELS

[does not include input or sub-out channels]

• resetInputs (selected [bool])
  Set input gains to unity
  Argument is optional: None or 0 = all, 1 = selected

• getChannels (selected [bool])
  Returns an array of mixer channels
  Argument is optional: None or 0 = all Channels, 1 = selected channels

• getChannelsByName (name [string], caseMatching [bool])
  Returns an array of mixer channels where the channel name contains the string.
  Optional case sensitivy matching: 0 or none = no case sensitivity, 1 = case sensitive

• getFader (channel [object])
  Returns a fader level in dB.

• setFader (channel [object], level [integer])
  Sets a fader to a specific dB value. -144 to 10

• setMasterFader (level [integer])
  Sets the master bus fader to a specific dB value.
  Example: setMasterFader( -10.5);

• setChannelColor (channel [object], color [hex])
  Sets a channel to a hex color, # char irrelevant

• centerPans ()
  Centers pans on all selected channel(s)

---

EXTERNAL INSTRUMENTS

You can use this function in your own custom patch manager script, to send program and bank changes out to MIDI hardware.

• setProgram (bank [integer], program [integer])
  Set bank and program for an external instrument

• loadCubasePatchFile (debug [integer])
  Returns an array from a Cubase patch script (.txt) file.
  Argument is optional. 1 = print array to console.
  Array item 0 is the Instrument Name, all other array items are comma delimited as follows:
  Program Name, program number, bank number, group name

---

MISCELLANEOUS

• Mute: if (track.channel != undefined) {track.channel.mute = 1};
• Solo: if {track.channel != undefined) {track.channel.solo = 1);
• Fire an Action: Host.GUI.Commands.interpretCommand("category","action")
• getDateTime (): Returns month/day/year (hour_minute_seconds)

---

SCRIPT PACKAGE EXAMPLE

A Studio One script package consists of (at minimum) three files as outlined below, zipped with a .package extender.
You can use this package to test various functions in functions.js.

metainfo.xml

Meta information for the script package.

Package:ID must be unique

<?xml version="1.0" encoding="UTF-8"?>
<MetaInformation>
    <Attribute id="Package:ID" value="test.functions"/>
    <Attribute id="Package:SkinFile" value="skin/"/>
    <Attribute id="Package:TranslationFile" value="translations/"/>
    <Attribute id="Package:Version" value="1.0.0/"/>
</MetaInformation>

classfactory.xml

Class definitions for each individual action.

ClassID's must be unique.
menuPriority value="-1" is don't list in menu

<?xml version="1.0" encoding="UTF-8"?>
<ClassFactory>
    <ScriptClass
	classID="{80CBE1FC-3EC1-4A97-A79E-FC46990FAEE8}"
	category="EditTask"
	subCategory="TrackEdit"
	name="TEST FUNCTIONS"
	sourceFile="code.js"
	functionName="createInstance"
	metaClassID="{B6099740-B26D-4BC3-A471-CBAAAED8CADC}">
	<Attribute id="menuPriority" value="0"/>
    </ScriptClass>
</ClassFactory>

code.js

JavaScript code file.

createInstance() is the entry function used by classFactory.xml in this example although the name of that function and of this js code file are both irrelevant, they only have to match the names used in classfactory.xml.

include_file('functions.js')
function testFunctions() 
{
    this.interfaces = [Host.Interfaces.IEditTask];

    this.prepareEdit = function (context)
    {        
        return Host.Results.kResultOk;
    }

    this.performEdit = function (context)
    {
        // ---------------------------------------
    	// return all tracks with 'voc' in the name
        var tracks = getTracksByName('voc')
        for (i = 0; i < tracks.length; i++)
        {
            // do something
        }
	
	// ----------------------------------------
	
        // test print Cubase patch script programs  
	// array to console, arg(1)
	// opens file selector dialog
        var inst = loadCubasePatchFile(1);
       
        return Host.Results.kResultOk;
    }
}

// Entry Function ---------------------------------

function createInstance ()
{
    return new testFunctions;
}