ForgeCut: Advanced User Guide

🖥️ For Windows Users

Simply open the folder where ForgeCut.exe is located. You will see several folders (effects, visualizers, transitions, templates, presets). Drop your custom files directly into these folders and restart the app.

🐧 For Linux (AppImage) Users

Because Linux .AppImage files act like read-only compressed zip files, the application cannot read new folders placed "next to" the AppImage. To add custom assets on Linux, you must extract the AppImage into a portable folder:

1. Open your terminal and extract the AppImage: ./Forge_Cut-x86_64.AppImage --appimage-extract
2. This creates a folder named squashfs-root. Rename this to ForgeCut.
3. Open ForgeCut/usr/bin/. This is your true application directory.
4. Place your folders (like effects and templates) inside this bin directory.
5. To launch the app, double-click the AppRun file inside the ForgeCut folder.

• /effects - Shows up in the "Effects Library" panel.
• /visualizers - Shows up in the "Audio Tools -> Audio Visualizer" dropdown.
• /transitions - Shows up in the "Effects Library" under Transitions.

ForgeCut automatically provides the following uniforms to your shaders:

uniform sampler2D texRGB;   // (The video frame)
uniform float iTime;        // (Playback time in seconds)
uniform vec2 iResolution;   // (Canvas width and height)
uniform vec3 iAudio;        // (Live audio reactivity! x = Bass, y = Mids, z = Treble)
varying vec2 vTexCoord;     // (UV coordinates, 0.0 to 1.0)

// --- ADVANCED UNIFORMS ---
uniform float opacity;      // IMPORTANT: Multiply your final gl_FragColor by this to support timeline fading!
varying vec2 vFragCoord;    // (Absolute pixel coordinates, identical to Shadertoy's gl_FragCoord.xy)
uniform vec2 texRes;        // (Alias for iResolution)

* Note: For Transitions, use sampler2D texA, sampler2D texB, and float progress instead of texRGB and iTime.

You do not need to write complex dampening or smoothing math for your audio visualizers. ForgeCut's C++ Audio Engine pre-processes the FFT data for you before it reaches the shader:

• Global Normalization: 1.0 represents the absolute loudest peak in the entire song. It will never clip.
• EMA Smoothing: An Exponential Moving Average (Alpha 0.3) is pre-applied for buttery smooth reactivity.
• Algorithmic Sync: The engine shifts the audio data back by exactly 83ms to perfectly counteract FFT latency, meaning your visualizer hits exactly on the drum kick.

uniform vec3 iAudio;

void main() {
    vec4 video = texture2D(texRGB, vTexCoord);
    // Flash the screen red to the bass!
    gl_FragColor = mix(video, vec4(1.0, 0.0, 0.0, 1.0), iAudio.x) * opacity;
}

uniform float iAudioSpectrum[64];

// 1. Safe Array Access
float getAudioRaw(int idx) {
    if(idx==0) return iAudioSpectrum[0]; else if(idx==1) return iAudioSpectrum[1];
    else if(idx==2) return iAudioSpectrum[2]; else if(idx==3) return iAudioSpectrum[3];
    else if(idx==4) return iAudioSpectrum[4]; else if(idx==5) return iAudioSpectrum[5];
    else if(idx==6) return iAudioSpectrum[6]; else if(idx==7) return iAudioSpectrum[7];
    else if(idx==8) return iAudioSpectrum[8]; else if(idx==9) return iAudioSpectrum[9];
    else if(idx==10) return iAudioSpectrum[10]; else if(idx==11) return iAudioSpectrum[11];
    else if(idx==12) return iAudioSpectrum[12]; else if(idx==13) return iAudioSpectrum[13];
    else if(idx==14) return iAudioSpectrum[14]; else if(idx==15) return iAudioSpectrum[15];
    else if(idx==16) return iAudioSpectrum[16]; else if(idx==17) return iAudioSpectrum[17];
    else if(idx==18) return iAudioSpectrum[18]; else if(idx==19) return iAudioSpectrum[19];
    else if(idx==20) return iAudioSpectrum[20]; else if(idx==21) return iAudioSpectrum[21];
    else if(idx==22) return iAudioSpectrum[22]; else if(idx==23) return iAudioSpectrum[23];
    else if(idx==24) return iAudioSpectrum[24]; else if(idx==25) return iAudioSpectrum[25];
    else if(idx==26) return iAudioSpectrum[26]; else if(idx==27) return iAudioSpectrum[27];
    else if(idx==28) return iAudioSpectrum[28]; else if(idx==29) return iAudioSpectrum[29];
    else if(idx==30) return iAudioSpectrum[30]; else if(idx==31) return iAudioSpectrum[31];
    else if(idx==32) return iAudioSpectrum[32]; else if(idx==33) return iAudioSpectrum[33];
    else if(idx==34) return iAudioSpectrum[34]; else if(idx==35) return iAudioSpectrum[35];
    else if(idx==36) return iAudioSpectrum[36]; else if(idx==37) return iAudioSpectrum[37];
    else if(idx==38) return iAudioSpectrum[38]; else if(idx==39) return iAudioSpectrum[39];
    else if(idx==40) return iAudioSpectrum[40]; else if(idx==41) return iAudioSpectrum[41];
    else if(idx==42) return iAudioSpectrum[42]; else if(idx==43) return iAudioSpectrum[43];
    else if(idx==44) return iAudioSpectrum[44]; else if(idx==45) return iAudioSpectrum[45];
    else if(idx==46) return iAudioSpectrum[46]; else if(idx==47) return iAudioSpectrum[47];
    else if(idx==48) return iAudioSpectrum[48]; else if(idx==49) return iAudioSpectrum[49];
    else if(idx==50) return iAudioSpectrum[50]; else if(idx==51) return iAudioSpectrum[51];
    else if(idx==52) return iAudioSpectrum[52]; else if(idx==53) return iAudioSpectrum[53];
    else if(idx==54) return iAudioSpectrum[54]; else if(idx==55) return iAudioSpectrum[55];
    else if(idx==56) return iAudioSpectrum[56]; else if(idx==57) return iAudioSpectrum[57];
    else if(idx==58) return iAudioSpectrum[58]; else if(idx==59) return iAudioSpectrum[59];
    else if(idx==60) return iAudioSpectrum[60]; else if(idx==61) return iAudioSpectrum[61];
    else if(idx==62) return iAudioSpectrum[62]; else if(idx==63) return iAudioSpectrum[63];
    return 0.0;
}

// 2. Ping-Pong utility
float pingPong(float x) { return abs(mod(x + 1.0, 2.0) - 1.0); }

// 3. Smooth Cubic Interpolation
float getAudio(float t) {
    t = pingPong(t); 
    float fIdx = t * 40.0; // Map 't' to lower 40 bins for visual punch
    
    int i = int(fIdx); float f = fract(fIdx);
    
    int i0 = int(max(0.0, float(i - 1))); int i1 = i;
    int i2 = int(min(63.0, float(i + 1))); int i3 = int(min(63.0, float(i + 2)));
    
    float v0 = getAudioRaw(i0); float v1 = getAudioRaw(i1);
    float v2 = getAudioRaw(i2); float v3 = getAudioRaw(i3);
    
    float p0 = (v2 - v0) * 0.5; float p1 = (v3 - v1) * 0.5;
    float t2 = f * f; float t3 = f * t2;
    
    float val = (2.0 * t3 - 3.0 * t2 + 1.0) * v1 + (t3 - 2.0 * t2 + f) * p0 + (-2.0 * t3 + 3.0 * t2) * v2 + (t3 - t2) * p1;
    return max(0.0, val);
}

// 4. Kernel Smoothing
float getSmoothedAudio(float t) {
    float sum = 0.0; float spread = 0.025;
    sum += getAudio(t - spread * 3.0) * 0.05; sum += getAudio(t - spread * 2.0) * 0.10;
    sum += getAudio(t - spread * 1.0) * 0.20; sum += getAudio(t)                * 0.30;
    sum += getAudio(t + spread * 1.0) * 0.20; sum += getAudio(t + spread * 2.0) * 0.10;
    sum += getAudio(t + spread * 3.0) * 0.05;
    return sum;
}

void main() {
    vec2 uv = vTexCoord;
    vec2 delta = uv - vec2(0.5);
    delta.x *= iResolution.x / iResolution.y; // Aspect correction
    
    float r = length(delta);
    float theta = atan(delta.y, delta.x); 
    float normalizedAngle = abs(theta) / 3.14159265;
    
    // Fetch smooth audio reactivity for this angle
    float audioReactivity = getSmoothedAudio(normalizedAngle);
    float circleRadius = 0.2 + (audioReactivity * 0.3);
    
    vec3 color = vec3(0.0);
    if (r < circleRadius) color = vec3(0.0, 1.0, 0.5); // Neon Green
    
    gl_FragColor = vec4(color, 1.0) * opacity;
}

ForgeCut parses special comments in your shader file and builds the UI automatically!

// @param float mySliderName 0.0 100.0 50.0
uniform float mySliderName;

// @param image dirtOverlay
uniform sampler2D dirtOverlay;

The @param image syntax creates a dropdown allowing the user to select any image from their Media Bin to feed directly into your shader.

For cinematic effects, you can create a Folder instead of a single file, and include a manifest.json. This allows you to run multiple shaders in sequence and load .cube 3D LUTs or local PNGs automatically!

// manifest.json
{
    "name": "Cinematic Look",
    "parameters": [
        { "name": "lutIntensity", "min": 0.0, "max": 1.0, "default": 1.0 }
    ],
    "assets": {
        "myLUT": "teal_orange.cube",
        "filmGrain": "grain.png"
    },
    "passes": ["colorgrade.frag"]
}

ForgeCut will automatically inject your assets as local_ prefixed uniforms. 3D LUTs are automatically mapped to sampler3D.

// colorgrade.frag
uniform sampler3D local_myLUT;     
uniform sampler2D local_filmGrain; 
uniform float lutIntensity;        

void main() {
    vec4 video = texture2D(texRGB, vTexCoord);
    vec4 graded = texture3D(local_myLUT, video.rgb); // 3D LUT Color Grading!
    gl_FragColor = mix(video, graded, lutIntensity) * opacity;
}

ForgeCut can automatically transcribe audio and generate animated, karaoke-style subtitles.

1. Select an audio or video clip containing speech on the timeline.
2. Open the Audio Tools panel on the right.
3. Click Auto-Subtitle with AI. (The Whisper AI model is pre-packaged with the editor, so no extra downloads are required!)

Translation Tip: You can export generated subtitles via File -> Export Texts as SRT, translate them using external tools, and bring them back using File -> Import Translated SRT.

ForgeCut supports commercial DAWs plugins (EQs, Compressors, Reverbs).

• Select an Audio clip, go to Audio Tools, and click Load VST3 Plugin.
• Check the "⏱ Automate" box in the Effect Controls panel to record live knob twists from the VST UI into timeline keyframes!

If GLSL isn't powerful enough, developers can write raw C++ plugins (OpenCV, AI upscaling, etc.).

• Select a Video clip, go to Effect Controls, and click Load Native Video Plugin.
• UI sliders will be automatically generated based on the C++ SDK exports.

1. Select a video clip and open the Effect Controls panel.
2. Click Start Object Tracking.
3. In the Preview Monitor, click and drag a line across the object you want to track (drawing a line provides scale and rotation data to the tracker).
4. The tracker will analyze forward and backward.
5. Change the Action dropdown to Center Object to automatically stabilize shaky footage around the tracked point.

Create a new folder inside your templates directory (e.g., /templates/my_overlay/) and add two files:

• index.html: Your actual webpage, styling, and JavaScript logic.
• manifest.json: Tells ForgeCut what sliders, text boxes, and color pickers to generate in the UI.

{
    "name": "Modern Lower Third",
    "defaultDuration": 5.0,
    "parameters": [
        { "name": "MainText", "type": "string", "defaultString": "JOHN DOE" },
        { "name": "BoxColor", "type": "color", "defaultColor": "#2a82da" },
        { "name": "Scale", "type": "float", "min": 0.5, "max": 2.0, "default": 1.0 }
    ]
}

ForgeCut communicates with your HTML file by automatically calling specific JavaScript functions. You just need to define them:

• setWebParameters(jsonStr): Called when a user types text, picks a color, or scrubs a slider. Also provides live audio data.
• seekTime(time): Called every frame. Provides the current timeline time in seconds so you can trigger CSS animations.

<!DOCTYPE html>
<html>
<head>
    <style>
        /* IMPORTANT: Ensure background is transparent so video shows through! */
        body { margin: 0; overflow: hidden; background: transparent; color: white; font-family: sans-serif; }
        #my-box { padding: 20px; font-size: 50px; display: inline-block; transition: transform 0.1s; }
    </style>
</head>
<body>
    <div id="my-box">Loading...</div>

    <script>
        // ForgeCut calls this when UI parameters or audio levels change
        function setWebParameters(jsonStr) {
            const params = JSON.parse(jsonStr);
            
            let box = document.getElementById('my-box');
            
            // Apply UI Parameters
            if (params.MainText !== undefined) box.innerText = params.MainText;
            if (params.BoxColor !== undefined) box.style.background = params.BoxColor;
            if (params.Scale !== undefined) box.style.transform = `scale(${params.Scale})`;

            // LIVE AUDIO REACTIVITY (Optional)
            // params.AudioLevels contains [Bass, Mids, Treble] (0.0 to 1.0)
            if (params.AudioLevels !== undefined) {
                let bass = params.AudioLevels[0];
                box.style.transform = `scale(${params.Scale + bass})`; // Pump to the beat!
            }
        }

        // ForgeCut calls this every frame
        function seekTime(time) {
            // e.g., Fade in after 1 second
            document.getElementById('my-box').style.opacity = time > 1.0 ? 1 : 0;
        }
    </script>
</body>
</html>

If your HTML template overlaps with an audio clip on the timeline, the jsonStr payload automatically includes an AudioSpectrum array containing 64 frequency bins. This allows you to easily build highly complex Canvas or WebGL audio visualizers in Javascript (using Three.js, p5.js, etc.) without writing a single line of C++ or GLSL backend code!