Utility Functions Collection
This is a reusable utility library module of small multi-step patterns that I keep repeating in everyday scripts and turned them into helpers, so individual scripts can stay focused on their actual logic.
This is a reusable utility library module of small multi-step patterns that I keep repeating in everyday scripts and turned them into helpers, so individual scripts can stay focused on their actual logic.
Copy and paste the txt contents in a script named _CommonFunctionsModule in the same folder as your other scripts you want to use these functions in and call it as below:
const Util = require('./_CommonFunctionsModule');
and then calling the functions as below
Util.initializeSfxIfAvailable();
const selected = Util.getSelectedTrackNames();
You can also use functions in here on their own by copying them into your script. Every call uses sf.app.proTools and sf.ui.proTools directly inside the function body, so you can copy any function in isolation without worrying about extra globals. Where one utility function depends on another, that dependency is mentioned in the function comment as Dependencies: so you know what to copy together.
What this covers:
Initialization and environment
Helpers to enable SFX when available and activate / invalidate Pro Tools only when needed.
initializeSfxIfAvailable turns on SFX only when available and not disabled in globalState.
activateProToolsMainWindowIfNeeded activates and invalidates Pro Tools only when you are not running inside the SFX app.
initializeProToolsSession gives you a single entry point for scripts that want SFX on plus a fresh track cache.
requireMinimumProToolsVersion wraps the version check and throws with your own message.
isRunningInSfxApplication is a small helper to branch logic when running in SFX vs classic.
Notifications
createNotificationHelper gives you a simple progress/notification object that reuses one notification ID.
showNotification is a one-shot wrapper for quick messages.
Timeline selection helpers
requireTimelineSelectionExists enforces that there is a non-zero timeline selection and throws if not.
restoreTimelineSelectionRange and setTimelineSelectionRange wrap getTimelineSelection / setTimelineSelection into clear verbs. The comments explain that the selection passed in should come directly from sf.app.proTools.getTimelineSelection() or from requireTimelineSelectionExists().
Track snapshots and filtered queries
getAllTracksDetails gives a full snapshot of every track with useful properties, including selectedState.
On top of that, getTrackNamesAndIndicesByFilter(trackType, stateFilter, selectionState) lets you get things like:
all Aux tracks
all muted Audio tracks
all BasicFolder tracks whose selectedState is SetExplicitly
It returns { name, index } and sorts by index so you can use the result directly for selection or routing logic.
Selected track helpers
These helpers always treat “selected” as selectedState === "SetExplicitly" so behaviour follows Pro Tools explicit selection instead of relying on isSelected.
getSelectedTrackNames returns the names of all tracks whose selectedState is SetExplicitly.
getSelectedNonFolderTrackNames returns explicitly selected tracks that are not any kind of folder.
getSelectedFolderTrackNames returns only the explicitly selected folder tracks.
Folder utilities
getAllFolderTrackNames, getFolderOpenPathForTracks and openTrackFoldersForTracks cover the “open only the folders needed for these tracks” pattern.
getFolderOpenPathForTracks checks for Pro Tools 2024.10+ internally and walks the parentFolderName chain so you get a complete list of all the tracks parents that can be passed straight to setTrackOpenState.
closeAllTrackFolders is a reset helper.
Track state utilities
getMuteStateMapForAllTracks builds a snapshot map you can store and restore later.
setMuteStateForTrackNames, setSoloStateForTrackNames, setHiddenStateForTrackNames are small wrappers for the corresponding Pro Tools APIs.
makeTrackNamesInactive, makeTrackNamesActive, hideAndDeactivateTrackNames, and hideAndDeactivateAllMutedTracks encode the selection + menu + hide workflow in clear functions.
setTrackHeightForFirstSelectedTrack lets you set track height using the header context menu, with a fallback for older layouts.
Insert, send, and plugin helpers
getInsertSlotInfoForTrackUi and getSendSlotInfoForTrackUi return arrays of { slot, value, isInactive, isAssigned } for a given track header.
findNextActiveInsertSlotNumber and findFirstActiveInsertSlotIndex make it easy to step through only active inserts.
findPluginOnTrackInserts(trackUi, pluginName) scans the insert buttons for an exact plugin label and returns both the zero-based slotIndex and the insert slotLetter a..j.
openPluginOnTrackByName(trackName, pluginName) combines this into a single call: it finds the track by name, finds the plugin by label, and clicks the right insert button. If the track or plugin is not found it throws a clear string error.
Plugin window helpers
closeAllPluginFloatingWindows closes any floating window whose title contains "Plug".
waitForPluginWindowByName(pluginName, timeoutMs) polls until a plugin window whose title contains the given name appears, or returns null after the timeout.
Clip and interval helpers
These work directly on sf.app.proTools.getSelectedClipInfo() and hide the usual interval merging and gap finding logic:
getClipIntervals(trackName) returns merged [start, end] pairs for all selected clips, or only for one track if you pass a name.
getClipIntervalsByTrack() returns a map from track name to merged intervals.
mergeIntervals(intervals) is the internal helper that merges overlaps.
intervalsOverlap(intervals, range) checks whether a candidate [start, end] would collide with any existing interval.
getGaps(intervals, rangeStart, rangeEnd) returns [start, end] pairs for the empty regions inside a given range.
The file includes commented example snippets that show how to use these helpers for tasks like “delete all gaps in a selection” or “check if a new clip would overlap existing clips”.
Memory locations and markers
getAllMemoryLocationMarkers returns a simple array of { name, number, time, comments }.
findMarkerByNameExact, jumpToMarkerByName, and getMarkersWithinTimeRange build on that for common marker lookups.
Confirmation dialog helpers
closeConfirmationDialogByButtons clicks the first matching button from a list like ["Remove", "Change", "OK", "Yes"] and waits for the dialog to disappear.
handleGenericConfirmationDialog is a simpler “OK / Option+Yes and wait for no modals” helper.
DAW commands with SFX + menu fallback
DAW_COMMANDS_WITH_FALLBACK is a table of common actions you already use in scripts: consolidate, separate, fades, edit modes, transport, selection linking, track operations, automation, playlists, and the main window commands.
runDawCommandWithFallback(key) looks up the entry, prefers the SFX DAW command when running in the SFX application, and falls back to a menuClick if needed.
How do I get Utility Functions Collection?
Utility Functions Collection is a package built on the SoundFlow platform. To get it, please follow these steps:
Sign up as a new SoundFlow user if you don't already have an account.
Install the SoundFlow app on your Mac.
Open up the SoundFlow app, click the "Store" tab
Locate the 'Utility Functions Collection' package by searching in the search field.
Click the Install button.