Project Name Field

Purpose: Defines the identifying label for the Final Cut Pro timeline and event generated during the ducking process.

Behavior:

• Accepts a custom text string that serves as the base name for all exported FCPXML elements
• Automatically populates when a dialogue audio file is dragged into the application by parsing the filename and removing standard Final Cut Pro export suffixes (such as " - 1-2 - All Dialogue")
• The entered value determines the Final Cut Pro event name (appended with _duck_event) and the project name (appended with _duck_project) in the generated timeline

Impact:

• Directly affects how the resulting ducked timeline is organized and identified within the Final Cut Pro library
• Provides consistent naming across the imported audio files, generated FCPXML, and any exported ducked audio files

Dialogue Audio File

Purpose: Defines the primary speech reference track used to detect active speaking segments that trigger volume attenuation on background audio tracks.

Behavior:

• Accepts audio files in standard formats, including WAV, AIFF, and MP3
• Automatically populates the project name field by parsing the filename and removing standard Final Cut Pro export suffixes
• Displays the filename and duration of the loaded audio
• The blue waveform visualization matches Final Cut Pro's dialogue track color convention

Impact:

• Serves as the master analysis track from which all speech clusters are derived
• Determines when the music, effects, and filler tracks receive volume reductions
• The threshold and hysteresis settings applied to this track control the sensitivity and release behavior of the entire ducking process

Music Audio File

Purpose: Defines the background music track that receives volume attenuation during detected speech segments.

Behavior:

• Accepts audio files in standard formats, including WAV, AIFF, and MP3
• Displays the filename and duration of the loaded audio
• The green waveform visualization matches Final Cut Pro's music track color convention

Impact:

• Volume is automatically reduced according to the configured attenuation level whenever dialogue is detected
• Transition timing (attack and release windows) controls how smoothly the volume changes
• The track can be attenuated to a specific decibel level or muted entirely during speech

---

Effects Audio File

Purpose: Defines the sound effects track that receives volume attenuation in parallel with the music track.

Behavior:

• Accepts audio files in standard formats, including WAV, AIFF, and MP3
• Displays the filename and duration of the loaded audio
• The cyan waveform visualization matches Final Cut Pro's effects track color convention

Impact:

• Volume is reduced according to the same attenuation settings applied to the music track
• Ducking occurs simultaneously with the music track whenever dialogue is detected
• Provides consistent volume balance across all non-dialogue audio elements

---

Role Control

Purpose: Configures the metadata role assigned to the secondary audio track in the generated Final Cut Pro timeline.

Behavior:

• Displays the currently selected role designation
• Opens a configuration sheet when activated
• Provides three role options:
• Dialogue: Assigns the dialogue role (blue track color)
• Music: Assigns the music role (green track color)
• Custom: Enables a text field for entering a unique role name

Impact:

• Determines how the track is categorized and color-coded when imported into Final Cut Pro
• Affects track grouping and organization within the Final Cut Pro timeline
• Custom roles allow for specialized workflow organization

---

Clear Control

Purpose: Removes the loaded effects audio file from the active session.

Behavior:

• Resets the effects path to an empty state
• Clears the waveform visualization from the drop zone
• Removes the track from processing during the ducking operation

Impact:

• The effects track will not receive volume ducking
• No effects-related keyframes or XML nodes are generated in the final output
• The track can be reloaded at any time by dragging a new audio file into the drop zone

Filler Audio File

Purpose: Defines an ambient, room tone, or atmosphere track that receives volume attenuation during detected speech segments, filling pauses in the music track to maintain continuous background texture.

Behavior:

• Accepts audio files in standard formats, including WAV, AIFF, and MP3
• Displays the filename and duration of the loaded audio
• The orange waveform visualization distinguishes it from the primary music track
• Role designation can be customized via the adjacent Role control

Impact:

• Receives volume ducking according to the same transition parameters applied to the music and effects tracks
• Provides flexible workflow options for managing separate background layers
• When multiple filler clusters are present, the application automatically inserts filler clips during gaps between detected speech segments, ensuring continuous ambiance throughout the timeline
• Removed from processing entirely when the clear control is used

Duck

Purpose: Executes the complete automatic audio ducking process, generating a keyframed timeline ready for Final Cut Pro.

Behavior:

• Validates that all required audio tracks (dialogue and music) are loaded and accessible
• Performs an integrity check on the loaded files, displaying warnings for missing or invalid paths
• Analyzes the dialogue track to identify active speech segments using the configured threshold and hysteresis settings
• Generates precise volume keyframes for the music, effects, and filler tracks
• Opens a progress panel that displays real-time status updates during processing
• Upon completion, either saves an FCPXML file to disk or sends the timeline directly to an open Final Cut Pro instance

Impact:

• The background audio tracks receive automated volume attenuation whenever speech is detected
• All transition timing (attack and release windows) is applied according to the configured parameters
• The resulting timeline preserves the original audio integrity while adding precise, editable keyframes
• The entire multi-track ducking process is completed in seconds, eliminating manual keyframing

---

Export Ducked Files

Purpose: Renders the ducked audio tracks directly to disk as processed WAV files, bypassing the FCPXML generation workflow.

Behavior:

• Available on macOS 12 and later
• Opens a configuration panel when activated
• Displays a list of tracks scheduled for export (music and effects)
• Allows selection of export destination:
• Subfolder of source: Creates an "AutoDucked Audio Files" folder adjacent to the original files
• Custom folder: Designates a specific output directory
• Provides bit depth selection:
• 16-bit: Standard CD quality
• 24-bit: Studio production depth
• 32-bit floating point: Maximum fidelity with zero clipping
• Applies the calculated speech clusters directly to the audio files
• Appends "_duck.wav" suffix to exported filenames
• Shows a progress indicator during rendering
• Automatically dismisses the panel upon completion

Impact:

• Produces physically processed audio files that can be directly imported into any audio or video editing software
• Eliminates the need for the FCPXML import step
• Supports iterative workflows where re-exporting overwrites previous files for easy updates
• Provides maximum audio quality with flexible bit depth options for different production requirements

1. Attack Window

Sets the duration of the volume fade-down transition. Determines how quickly the background audio drops to its ducked level once speech is detected. A shorter value produces an abrupt drop, while a longer value creates a gradual, smooth fade.

2. Attack Pre-Roll

Sets the lead time before speech begins for the fade-down to start. Ensures that the initial consonants or first syllables of dialogue are not obscured by the background audio.

3. Release Window

Sets the duration of the volume fade-up transition. Governs how smoothly the background audio returns to its normal level after speech ends. A longer value results in a more gradual and natural-sounding recovery.

4. Release Pre-Roll

Sets the hold time after speech ends before the fade-up transition starts. Keeps the background audio ducked during natural pauses between sentences, preventing unwanted volume pumping.

1. Threshold

Sets the amplitude level in decibels (dB) that triggers the ducking effect. Any dialogue signal that rises above this level is detected as active speech, prompting the background audio to lower its volume. Lowering the value makes the system more sensitive, catching softer speech, while raising it ensures that only louder dialogue triggers the ducking.

2. Hysteresis

Sets a secondary, lower amplitude offset in decibels (dB) that determines when the ducking effect releases. Active speech is considered to have ended only when the dialogue signal drops below the calculated value of Threshold - Hysteresis. This gap prevents the system from rapidly turning on and off during natural volume decays, soft consonants, or short pauses, ensuring smooth and stable transitions.

1. Decrease to (Zero / -∞ dB)

When active, forces the background audio volume to a complete mute (-∞ dB) during speech segments. This overrides any value set on the attenuation slider, ensuring absolute silence from the background tracks while dialogue is present.

2. Decrease to (-15 dB)

When the mute option is inactive, this controls the exact amount of attenuation applied to the background audio during speech. A value of -15 dB means the background tracks are lowered to 15 decibels below their normal level, creating a clear separation between dialogue and the supporting audio.

3. Overall Level

Sets the baseline master volume for the background audio tracks during silent periods. This offset acts as a global gain control for the music and effects tracks, scaling their default level relative to the dialogue.

1. Export for Final Cut Pro 10.6+

Specifies the target format for the generated timeline. When active, the output conforms to the FCPXML v1.10 schema, which is native to Final Cut Pro 10.6 and newer. When inactive, the output uses a legacy schema compatible with older versions.

2. Remember My Choice

Persists the selected export format preference. When active, the version confirmation dialog is bypassed on subsequent exports, using the cached choice automatically. When inactive, the system prompts for the format selection each time.

3. Send Immediately to Final Cut Pro without Saving FCPXML

Determines how the processed timeline is delivered. When active, the keyframed sequence is sent directly to an open instance of Final Cut Pro via system events, bypassing the creation of a physical FCPXML file on disk. When inactive, a standard FCPXML file is written to the filesystem for manual import.