Image Melody Loader

/**
 * Creates an animated "melody loader" effect over an image.
 * This effect simulates a wavy scanner bar revealing the image underneath,
 * giving a visual impression of "loading" with a musical or melodic feel.
 * The animation loops continuously.
 *
 * @param {HTMLImageElement} originalImg The original image to process.
 * @param {string} loaderColor The color of the overlay. Should be in a format like 'rgba(0, 0, 0, 0.6)'.
 * @param {number} scanSpeed The speed at which the scanner wave moves across the image (pixels per frame).
 * @param {number} waveAmplitude The horizontal amplitude (width) of the wave effect.
 * @param {number} waveFrequency The vertical frequency of the wave. Higher numbers mean more curves.
 * @returns {HTMLCanvasElement} A canvas element with the animated effect.
 */
function processImage(originalImg, loaderColor = 'rgba(0, 0, 0, 0.6)', scanSpeed = 2, waveAmplitude = 25, waveFrequency = 0.04) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    const {
        width,
        height
    } = originalImg;
    canvas.width = width;
    canvas.height = height;

    // Width of the revealing scanner wave
    const waveRevealWidth = width / 3;
    let progress = 0;

    function animate() {
        // progress moves from off-screen left to off-screen right, then loops
        progress = (progress + scanSpeed) % (width + waveRevealWidth);

        // Current position of the left edge of the wave starts off-screen
        const waveLeft = progress - waveRevealWidth;

        // 1. Clear canvas and draw the main image as the base layer
        ctx.clearRect(0, 0, width, height);
        ctx.drawImage(originalImg, 0, 0, width, height);

        // 2. Create the loader overlay.
        // We do this by defining two paths: one for the entire canvas boundary
        // and a second for the moving wave. By using the 'evenodd' fill rule,
        // we can fill the area that is inside the first path but outside the second,
        // effectively punching a hole in the overlay where the wave is.
        ctx.beginPath();

        // First sub-path: the entire canvas
        ctx.rect(0, 0, width, height);

        // Second sub-path: the revealing wave
        const waveRight = waveLeft + waveRevealWidth;
        ctx.moveTo(waveLeft, 0); // Top-left of wave
        ctx.lineTo(waveRight, 0); // Top-right of wave
        for (let y = 0; y <= height; y++) {
            // Add progress to the sine function to make the wave appear to ripple as it moves
            const xOffset = Math.sin((y * waveFrequency) + (progress / 20)) * waveAmplitude;
            ctx.lineTo(waveRight + xOffset, y);
        }
        ctx.lineTo(waveLeft, height); // Bottom-left of wave
        ctx.closePath();

        // Fill the area defined by the 'evenodd' rule
        ctx.fillStyle = loaderColor;
        ctx.fill('evenodd');

        // Continue the animation loop only if the canvas is still part of the webpage
        if (canvas.isConnected) {
            requestAnimationFrame(animate);
        }
    }

    // Start the animation
    animate();

    return canvas;
}