Item FX Inspector

Inspect and adjust the active take’s item FX and utility properties while you work.

Contents

1. Quick start: 60 seconds
2. What it does and when to use it
3. Window and lifecycle
4. Utility block
5. Device cards
6. Controls and interaction
7. Mappings
8. Themes
9. Settings reference
10. Use cases
11. Troubleshooting
12. FAQ
13. Appendix

Quick start: 60 seconds

1. Run the Item FX Inspector action.
2. Select an item with an active take. The body begins with Editing: <take name> - <N> items selected.
3. Hover a utility or FX knob and scroll, or click-drag vertically. Up increases a value.
4. Use the Utility block for volume, pan, pitch, rate, preserve pitch, and loop source.
5. Use device cards for mapped take-FX controls. Click a device title to open its native UI; right-click it to customise the mapping.
6. Open Settings to select the theme, modifier scheme, fallback controls, UI scale, visibility, and utility defaults.

Tip: Start with Host convention. Use Inverted if you prefer Shift for fine wheel changes and Ctrl/Cmd for coarse wheel changes.

What it does and when to use it

Item FX Inspector gives you a focused surface for the active take of the first selected item. You can make quick item-level changes without opening each plug-in window, while the device cards retain a direct route to the native UI.

Use it for

• shaping a vocal chop with a mapped equaliser and its Wet blend;
• trimming level and driving a saturation control;
• preparing a pitched or looping sample;
• applying utility defaults to selected items one at a time;
• curating a third-party plug-in mapping;
• taming a transient with parallel compression;
• building a quick delay throw; and
• auditioning item FX during playback.

It does not currently do

• track FX inspection;
• broadcasting edits to multiple items;
• macros;
• MIDI learn; or
• per-instance overrides.

Limitation: Phase 1 edits only the active take of the first selected item. The selected-item count is informational; there is no multi-item broadcast.

Window and lifecycle

On startup, the normal console line is Item FX Inspector: startup caps {...} ctx=yes. The window titlebar reads Item FX Inspector. The body line uses the exact form Editing: <take name> - <N> items selected, with an ASCII hyphen.

With a selected item and active take, the view follows that target. With no selection it shows dimmed No item selected and Settings. With no active take it shows dimmed No active take and Settings. The default is persistent; you can opt in to Hide floating window when no item is selected for Floating mode.

An empty FX chain shows a Utility card and a + add FX card. After six or more consecutive errors, a static reload notice is shown. Item, take, and FX deletion is checked safely on each tick.

There is no close (X) button. Stop the script through REAPER’s ReaScript task control, or re-run it and terminate it there.

The default window is 860x420 at the top right of the viewport work area; the fallback position is 120,120. Position and size are persisted in the ContextItemFX ExtState section as win_x, win_y, win_w, and win_h, with a 0.35-second debounce. A minimum size is enforced. Floating is the default; Docked is capability-gated. If docking is unavailable, the console prints once Item FX Inspector: Docked mode unavailable on this ReaImGui build; using Floating.

The window is designed so that it does not steal focus when it appears. It does not bring itself to the front, and its wheel input is limited to a hovered, non-dragged knob. A short 0.18-second click-through guard follows (re)appearance. Text fields in Search, Rename, and clamp dialogs take focus while you edit them; a native plug-in window can also take focus.

The window is designed so that its model is rebuilt only when the selection or content changes, while reads are limited to drawn controls and operations are protected against item, take, and FX deletion. It defers updates by about 33 ms. These are design characteristics, not performance measurements.

Only one instance runs. A second launch reports Item FX Inspector: instance diagnostic instances_detected=1 lock=refused owner=<n>.

When collapsed, the script draws nothing and closes the window scope once.

Important: N items selected does not mean all selected items are edited. Every edit targets the active take of the first selected item only.

Utility block

The Utility card contains two always-visible checkboxes and four configurable knobs. The checkboxes use the exact lowercase labels preserve pitch and loop source.

Volume’s minimum displays -inf dB but is not silence: the value written is -60 dB. The utility knobs use a segmented automatic arc. Volume, Pitch, and Rate writes call UpdateItemInProject.

In Settings, clear or select Volume, Pan, Pitch, and Rate in Utility controls Volume/Pan/Pitch/Rate. The default is all four. preserve pitch and loop source remain visible regardless of that setting.

Set Default preserve pitch and Default loop source before using Apply defaults to selected item. That button applies only the two defaults, not Volume, Pan, Pitch, or Rate, and creates one undo entry: Apply utility defaults (Take/Item).

Device cards

Each device card is 286scale high and has a width of max(144, ceil(visible_controls/3)*64)*scale. A device with no visible controls is header-only. Controls are arranged three per column, top-to-bottom and then left-to-right; each cell is 60x82scale.

The header strips a format prefix from the device name. For example, VST3: ReaEQ (Cockos) displays ReaEQ. Long names are truncated with ..; hover to see the full name. An unsaved session mapping edit adds * to the name.

• Left-click the device name to float the native UI. This is best-effort, ignored with a modifier, during the 0.18-second guard, or while the FX is offline.
• Right-click the device name for the device menu.
• Use the 18*scale power button to bypass or enable the device. Its tooltip is Bypass FX or Enable FX; it is ignored while offline.
• A 22x22 Wet mini-knob appears only when the plug-in exposes :wet; its tooltip shows the current Wet value.
• An offline device shows OFFLINE, 45% alpha, and diagonal hatching. All writes are refused.
• The last column can contain the + add FX card. Its tooltip is Open the take FX add browser (best effort).

Controls show a knob, label, and live readout. Two-state parameters render as switches with On or Off. A parameter is classified as two-state from its reported toggle step, a whole-span step, or an identifier/name token such as bypass, enabled, onoff, mute, or solo. A continuous parameter named Bypass Amount is deliberately not a toggle.

State marks

The horizontal device flow uses a table with a horizontal scrollbar and inner vertical borders. Navigate with the scrollbar or a wider window; the window does not capture the wheel for this lane.

Controls and interaction

Host convention

The wheel works only over a hovered, non-dragged knob. Use the horizontal scrollbar to move along the device lane. For a different feel, choose Inverted in Settings.

Inverted scheme

Inverted swaps the wheel modifiers and changes the drag modifier as follows.

Double-click reset always works. Reset uses the plug-in default from GetParamEx where available, otherwise the centre of the range; Utility controls use their exact defaults above. Stepped controls snap to the plug-in grid on absolute 0..1 and then clamp into the window. Toggles snap to 0 or 1.

Right-click Set range clamp… to set normalised 0..1 bounds. The dialog has Min, Max, Capture min, Capture max, Clear, Apply, and Cancel. It requires 0<=min<max<=1.

Every control tooltip ends with Right-click for options (rename, hide, clamp, ...).

Undo and envelopes

Each gesture is designed to create one undo entry. A drag commits on release. A wheel burst is coalesced after about 0.5 seconds idle, never while the mouse is held; a leaked hold is retired after 1.5 seconds, with a 5.0-second ceiling. Moving to another control commits the first block, and an open block is committed at exit.

An envelope badge is E when a take envelope is present; the last write wins. Mapping-layout edits change configuration rather than audio.

Control menu

The exact control menu order is:

1. Reset (greyed for missing parameters)
2. Set range clamp…
3. Rename…
4. separator
5. Hide
6. Remove
7. Move left
8. Move right
9. separator
10. MIDI learn — later (greyed), with tooltip MIDI learn is planned for a later phase

Limitation: MIDI learn is a greyed placeholder, not an available feature.

Mappings

Mapping priority is session, then user, then shipped.

Both JSON mapping files use schema_version: 1 and atomic writes. If the user file is corrupt it is renamed to .bak with a console note; it is never blindly overwritten.

A mapping identity is normalised from fx_ident, then TakeFX_GetIdent, then the normalised name. A mapping saved against a VST3 build also applies to CLAP, AU, and VST2 builds. Validation first checks the name at the index, then rescans by name. The latter shows tooltip Resolved by parameter name. If neither works, the row stays as missing and disabled rather than silently selecting a wrong parameter.

An unmapped plug-in automatically exposes the first N parameters, default 8, in the range 0..32. A value of 0 gives a header-only card. The scan and picker cap is 512. Noise parameters are skipped when their identifier or name contains any of: wet, bypass, delta, dry, mono, stereo. This includes names such as Wet Mix, Dry Level, and Stereo Width.

Add and curate controls

1. Open the device menu and choose Add control….
2. Search the scrollable list with the case-insensitive Search field. Already mapped parameters are marked [mapped].
3. Select a parameter and choose Add, or choose Cancel.
4. Use the control menu to Rename…, set a range clamp, Hide, Remove, or Move left/Move right.
5. Choose Save as my default in the device menu to persist the mapping. This clears *.

The optional touch-to-map mode is armed by opening the picker, polls at 4 Hz, and self-disarms after 30 seconds. It requires GetTouchedOrFocusedFX; otherwise the picker footer says touch-to-map unavailable. The picker is the reliable path.

Use the device menu’s Show entries to restore hidden controls. Hide keeps a row so you can restore it; Remove deletes the row. Reset to shipped default asks Reset this device to its shipped default? before proceeding.

Note: Session mapping edits are unsaved until you choose Save as my default. User mappings are retained when shipped mappings are updated.

Themes

Choose Theme in Settings. The eight themes are:

1. REAPER 7 (default)
2. Tokyo Sunrise
3. Tokyo Night
4. Nord
5. Dracula
6. Gruvbox
7. Solarized Dark
8. Catppuccin Mocha

The theme is persisted under the lowercase key theme. An unknown stored name falls back to REAPER 7. The theme affects the inspector only; UI scale is independent.

Settings reference

The window position and size are saved automatically as win_x, win_y, win_w, and win_h; docking uses dock_id. Run bookkeeping uses running and context_serial in the ContextItemFX ExtState section.

Tip: If 100% looks small on a HiDPI display, point the UI scale at 125-150%.

Use cases

1. Darken a vocal chop

Goal: Make a vocal chop sit behind the lead.

Steps:

1. Select the vocal item and run the action.
2. On its ReaEQ card, adjust the high-shelf or low-pass control.
3. Adjust the Wet knob to blend the result.

Why it works: The mapped controls and Wet blend keep the tonal change close to the item.

Related settings: Utility controls Volume/Pan/Pitch/Rate, Theme, and the mapping controls.

2. Quick trim and drive

Goal: Set level and add saturation without leaving the item view.

Steps:

1. Adjust Volume in the Utility block.
2. On the saturation device, adjust Drive or Gain.
3. If it is not mapped, use Add control….
4. Set Wet or use the bypass power button to compare.

Why it works: Utility level and the selected device controls are available in one view.

Related settings: Fallback controls and device mapping menus.

3. Prepare a pitched or looping sample without FX

Goal: Make a sample follow the musical part before adding effects.

Steps:

1. Turn on loop source if the source must loop.
2. Turn on preserve pitch if playback rate changes should not change pitch.
3. Set Pitch, Rate, Pan, and Volume as needed.

Why it works: These utility controls address item and take properties directly.

Related settings: Default preserve pitch, Default loop source, and Utility controls Volume/Pan/Pitch/Rate.

4. Bulk-prep a group of samples safely

Goal: Repeat the same two utility defaults while retaining one-target safety.

Steps:

1. Set Default preserve pitch and Default loop source.
2. Select one sample and choose Apply defaults to selected item.
3. Repeat for each sample, checking the active take before applying.

Why it works: The operation makes one undo entry and applies only the two defaults.

Related settings: Apply defaults to selected item and the two default checkboxes.

Limitation: Selected items are not edited together; each invocation targets the first selected item’s active take.

5. Curate a third-party plug-in mapping

Goal: Keep the useful parameters visible and named for your work.

Steps:

1. Open the device menu and choose Add control….
2. Search and add the parameters you need.
3. Rename, clamp, hide, or reorder controls from their right-click menus.
4. Choose Save as my default.

Why it works: Your user mapping is separate from shipped defaults and is not overwritten by updates.

Related settings: Fallback controls and the device menu.

6. Tame a transient with parallel compression

Goal: Control a transient while retaining a parallel blend.

Steps:

1. On ReaComp, adjust Threshold, Ratio, Attack, and Release.
2. Set Wet to blend the compressed signal.
3. Use bypass to compare the result.

Why it works: ReaComp ships with seven mapped controls, while Wet and bypass remain directly available.

Related settings: Theme, Modifier scheme, and ReaComp mapping controls.

7. Build a quick delay throw

Goal: Add a controllable delay accent to an item.

Steps:

1. On ReaDelay, adjust Length, Feedback, and Filter.
2. Set Wet for the throw level.
3. Bypass the device to audition the dry result.

Why it works: ReaDelay ships with seven mapped controls and direct Wet/bypass access.

Related settings: Modifier scheme and device mapping controls.

8. Audition item FX during playback

Goal: Compare settings while playback continues.

Steps:

1. Start playback and select an item.
2. Adjust Wet or bypass the device for quick comparisons.
3. Select another item to follow its active take.
4. If you need text entry, use a Search, Rename, or clamp field, then close the popup or click Arrange to return keyboard input.

Why it works: The inspector follows selection while its focus safeguards avoid taking focus on appearance.

Related settings: Display mode, Hide floating window when no item is selected, and Theme.

Troubleshooting

No window after selecting an item

Run the action, confirm ReaImGui 0.9.x (API 0.9.3), and select an item with an active take. If a reload notice appears, check the console for an error. Try Floating if you selected Docked.

“No item selected”

This is the normal empty state. Select an item, or enable Hide floating window when no item is selected if you prefer the Floating window to hide.

Docked mode is unavailable

Docking is capability-gated. Update ReaImGui if appropriate, or use Floating, which is the default.

The theme looks wrong

Choose REAPER 7. Update the script and restart after an update; a red or washed appearance can indicate an obsolete build.

Keyboard transport or focus is unexpected

The window is designed not to take focus on appearance. Search, Rename, and clamp fields take input while open; close the popup or click Arrange afterwards. Opening a native plug-in UI gives it focus.

A control is missing or disabled

If the card says OFFLINE, bring the FX online. If you see the ! crossed mark, the parameter was not found; remove and re-add it, then save the mapping.

Mapping edits disappear after restart

A * marks unsaved session edits. Open the device menu and choose Save as my default.

Touch-to-map is unavailable

Use the Add control… picker. Touch-to-map is experimental and needs GetTouchedOrFocusedFX.

Scrolling moves a control instead of the lane

Wheel input is captured only over a hovered knob. Move the pointer away from knobs and use the horizontal scrollbar for the lane.

FAQ

Does it inspect track FX?

No. It works with take FX and item/take Utility controls.

Does it work with MIDI items?

An active take is required; the inspector edits the first selected item’s active take.

Are all selected items edited together?

No. Phase 1 targets only the first selected item’s active take. Broadcast is planned for a later phase.

Can I open the full plug-in window?

Yes. Click the device title; opening the native UI is best-effort.

What is the difference between Hide and Remove?

Hide keeps the row and lets you restore it with Show in the device menu. Remove deletes the row.

What does * mean?

It marks an unsaved session mapping edit. Save with Save as my default.

Will updates overwrite my mappings?

Shipped mappings may be replaced by an update. mappings/user-overrides.json is kept.

Can one control drive several parameters?

Not in Phase 1.

Is MIDI learn available?

No. MIDI learn — later is a deliberately greyed placeholder.

What does the E badge mean?

A take envelope is present. The last write wins.

Why is a missing parameter still shown?

Keeping the disabled row avoids silently wiring the wrong parameter and preserves the mapping row.

Do mappings work between VST3 and CLAP?

Mappings use normalised cross-format identity, so a mapping saved against a VST3 build also applies to CLAP, AU, and VST2 builds when validation succeeds.

Appendix

Exact undo labels

A drag creates one entry on release. A wheel burst groups after about 500 ms idle. Bypass and Enable have no Adjust prefix.

Install

Item FX Inspector is installed in REAPER’s Scripts/ContextItemFX folder. The internal folder and script names remain unchanged.

Requirements: REAPER 7.78-compatible take-FX API and ReaImGui v0.9.x API 0.9.3. js_ReaScriptAPI is not required.

Manual installation

1. Choose Options > Show REAPER resource path.
2. Open Scripts and copy the ContextItemFX folder there.
3. Load ContextItemFX.lua as a ReaScript action.
4. Run the action.

ReaPack installation

When published, add the repository URL to ReaPack, sync, install the package, install ReaImGui, and run the action. There is no public ReaPack remote yet; a local repository is available at reapack-dist/.

Preserved user data

User mappings are stored at Scripts/ContextItemFX/mappings/user-overrides.json and are not overwritten by shipped-mapping updates.