<?php
/**
 * SeekQuarry/Yioop --
 * Open Source Pure PHP Search Engine, Crawler, and Indexer
 *
 * Copyright (C) 2009 - 2026  Chris Pollett chris@pollett.org
 *
 * LICENSE:
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 * END LICENSE
 *
 * @author Chris Pollett chris@pollett.org
 * @license https://www.gnu.org/licenses/ GPL3
 * @link https://www.seekquarry.com/
 * @copyright 2009 - 2026
 * @filesource
 *
 * PlainSound reads and writes the two sound files that store their
 * samples as they are, rather than compressing them.
 */
namespace seekquarry\yioop\library\av_processing;

/**
 * PlainSound reads and writes sound files that keep their samples as
 * they are: the WAV file a recorder or an editor writes, and the AIFF
 * file that does the same on Apple machines. The two differ in the
 * order their bytes run and in how they name their parts, and in
 * nothing else that matters here.
 *
 * A caller reads a file a piece at a time and writes one the same way,
 * so a recording of any length passes through without being held in
 * memory. AudioConverter uses this class as both a source of samples
 * and a place to put them.
 *
 * @author Chris Pollett
 */
class PlainSound
{
    /**
     * HEADER_BYTES is how many bytes the description at the front of a
     * WAV file takes when this class writes one. A player reads the
     * length of the sound out of it, so it is written again once the
     * sound is finished and its length is known.
     * @var int
     */
    const HEADER_BYTES = 44;
    /**
     * AIFF_HEADER_BYTES is the same count for an AIFF file, which
     * names its parts differently and so takes a few more bytes.
     * @var int
     */
    const AIFF_HEADER_BYTES = 54;
    /**
     * SAMPLE_BYTES is how many bytes one sample takes in the files this
     * class reads and writes. Two bytes hold a sample finely enough
     * that a listener hears no difference from the recording.
     * @var int
     */
    const SAMPLE_BYTES = 2;
    /**
     * FULL_SCALE is the value a sample takes at the loudest a file of
     * this kind can hold. A sample arrives as a fraction of one and is
     * multiplied by this before it is written.
     * @var int
     */
    const FULL_SCALE = 32767;
    /**
     * READ_SAMPLES is how many samples are read from a file at a time.
     * A few thousand keeps the memory a reading needs flat, whatever
     * the length of the file.
     * @var int
     */
    const READ_SAMPLES = 24000;
    /**
     * kindOf says which kind of plain sound file a file holds, reading
     * its first bytes rather than trusting its name. A caller uses this
     * before opening a file, so that a WAV named as an AIFF is still
     * read correctly.
     *
     * @param string $path The file to look at.
     * @return string The word wav or aiff, or an empty string where the
     *     file is neither.
     */
    public static function kindOf($path)
    {
        $handle = @fopen($path, "rb");
        if ($handle === false) {
            return "";
        }
        $head = fread($handle, 12);
        fclose($handle);
        if (strlen($head) < 12) {
            return "";
        }
        if (substr($head, 0, 4) === "RIFF"
            && substr($head, 8, 4) === "WAVE") {
            return "wav";
        }
        if (substr($head, 0, 4) === "FORM"
            && (substr($head, 8, 4) === "AIFF"
            || substr($head, 8, 4) === "AIFC")) {
            return "aiff";
        }
        return "";
    }
    /**
     * describe says what a plain sound file holds: how it is stored,
     * how many samples a second it was recorded at, how many channels
     * it carries, and how long it runs. Nothing is decoded, so this is
     * quick whatever the length of the file.
     *
     * @param string $path The file to look at.
     * @param string $kind The word wav or aiff, as kindOf gave it.
     * @return array What the file says about itself, keyed by
     *     container, rate, channels and seconds.
     */
    public static function describe($path, $kind)
    {
        $said = self::readHeader($path, $kind);
        $each = max(1, $said["rate"] * $said["channels"]);
        return ["container" => $kind, "rate" => $said["rate"],
            "channels" => $said["channels"],
            "seconds" => round($said["samples"] / $each, 3)];
    }
    /**
     * readHeader reads the description at the front of a plain sound
     * file: where its samples begin, how many there are, how fast they
     * were recorded, and in how many channels. A reader needs all four
     * before it can hand back a single sample.
     *
     * @param string $path The file to read.
     * @param string $kind The word wav or aiff, as kindOf gave it.
     * @return array The description, keyed by at, samples, rate,
     *     channels and bits.
     */
    public static function readHeader($path, $kind)
    {
        $handle = fopen($path, "rb");
        if ($handle === false) {
            throw new \RuntimeException("$path cannot be read");
        }
        $said = ($kind === "wav") ? self::readWavHeader($handle)
            : self::readAiffHeader($handle);
        fclose($handle);
        return $said;
    }
    /**
     * readWavHeader walks the named parts of a WAV file until it has
     * found the one describing the sound and the one holding it. A file
     * may carry other parts, such as a title or a marker, and those are
     * stepped over.
     *
     * @param resource $handle The open file, at its start.
     * @return array The description, keyed by at, samples, rate,
     *     channels and bits.
     */
    public static function readWavHeader($handle)
    {
        fseek($handle, 12);
        $rate = 0;
        $channels = 1;
        $bits = 16;
        while (!feof($handle)) {
            $head = fread($handle, 8);
            if (strlen($head) < 8) {
                break;
            }
            $name = substr($head, 0, 4);
            $length = unpack("V", substr($head, 4, 4))[1];
            if ($name === "fmt ") {
                $said = fread($handle, $length);
                $channels = max(1, unpack("v", substr($said, 2, 2))[1]);
                $rate = unpack("V", substr($said, 4, 4))[1];
                $bits = unpack("v", substr($said, 14, 2))[1];
                continue;
            }
            if ($name === "data") {
                return ["at" => ftell($handle),
                    "samples" => intdiv($length, max(1, intdiv($bits, 8))),
                    "rate" => $rate, "channels" => $channels,
                    "bits" => $bits];
            }
            fseek($handle, $length + ($length & 1), SEEK_CUR);
        }
        throw new \RuntimeException("this WAV file holds no sound");
    }
    /**
     * readAiffHeader does the same walk for an AIFF file, whose parts
     * carry different names and whose numbers run the other way round.
     * The rate is written as a wide floating point number of a shape no
     * other part of the file uses, so it is read here by hand.
     *
     * @param resource $handle The open file, at its start.
     * @return array The description, keyed by at, samples, rate,
     *     channels and bits.
     */
    public static function readAiffHeader($handle)
    {
        fseek($handle, 12);
        $rate = 0;
        $channels = 1;
        $bits = 16;
        $samples = 0;
        while (!feof($handle)) {
            $head = fread($handle, 8);
            if (strlen($head) < 8) {
                break;
            }
            $name = substr($head, 0, 4);
            $length = unpack("N", substr($head, 4, 4))[1];
            if ($name === "COMM") {
                $said = fread($handle, $length);
                if (strlen($said) < 18) {
                    break;
                }
                $channels = max(1, unpack("n", substr($said, 0, 2))[1]);
                $samples = unpack("N", substr($said, 2, 4))[1] * $channels;
                $bits = unpack("n", substr($said, 6, 2))[1];
                $rate = self::readWideRate(substr($said, 8, 10));
                continue;
            }
            if ($name === "SSND") {
                $ahead = fread($handle, 8);
                $skip = unpack("N", substr($ahead, 0, 4))[1];
                fseek($handle, $skip, SEEK_CUR);
                return ["at" => ftell($handle), "samples" => $samples,
                    "rate" => $rate, "channels" => $channels,
                    "bits" => $bits];
            }
            fseek($handle, $length + ($length & 1), SEEK_CUR);
        }
        throw new \RuntimeException("this AIFF file holds no sound");
    }
    /**
     * readWideRate turns the ten byte number an AIFF file writes its
     * recording rate as into an ordinary one. The first two bytes hold
     * how far the point has moved and the other eight hold the digits,
     * a shape from older machines that no other part of these files
     * uses.
     *
     * @param string $held The ten bytes as the file stored them.
     * @return int How many samples a second the file was recorded at.
     */
    public static function readWideRate($held)
    {
        if (strlen($held) < 10) {
            return 0;
        }
        $moved = unpack("n", substr($held, 0, 2))[1];
        $upper = unpack("N", substr($held, 2, 4))[1];
        $lower = unpack("N", substr($held, 6, 4))[1];
        $whole = $upper * 4294967296.0 + $lower;
        $shift = $moved - 16383 - 63;
        return (int)round($whole * pow(2.0, $shift));
    }
    /**
     * eachPiece hands back the samples of a plain sound file a few
     * thousand at a time, as fractions of one. Where a file carries
     * more than one channel they are averaged into one, since what this
     * folder writes carries a single channel.
     *
     * @param string $path The file to read.
     * @param string $kind The word wav or aiff, as kindOf gave it.
     * @return Generator Runs of samples, each between one below zero
     *     and one above it.
     */
    public static function eachPiece($path, $kind)
    {
        $said = self::readHeader($path, $kind);
        $handle = fopen($path, "rb");
        if ($handle === false) {
            throw new \RuntimeException("$path cannot be read");
        }
        fseek($handle, $said["at"]);
        $wide = ($kind === "wav") ? "v" : "n";
        $left = $said["samples"];
        $channels = $said["channels"];
        while ($left > 0 && !feof($handle)) {
            $wanted = min($left, self::READ_SAMPLES);
            $bytes = fread($handle, $wanted * self::SAMPLE_BYTES);
            if ($bytes === false || $bytes === "") {
                break;
            }
            $read = unpack($wide . "*", $bytes);
            $run = [];
            $held = 0.0;
            $seen = 0;
            foreach ($read as $value) {
                if ($value >= 32768) {
                    $value -= 65536;
                }
                $held += $value / self::FULL_SCALE;
                $seen++;
                if ($seen === $channels) {
                    $run[] = $held / $channels;
                    $held = 0.0;
                    $seen = 0;
                }
            }
            $left -= $wanted;
            yield $run;
        }
        fclose($handle);
    }
    /**
     * startWriting opens a plain sound file and writes room for its
     * description, which cannot be filled in until the length of the
     * sound is known. A caller adds samples with addPiece and closes
     * the file with finishWriting.
     *
     * @param string $path Where to write the file.
     * @param string $kind The word wav or aiff.
     * @param int $rate How many samples a second the sound runs at.
     * @return resource The open file, ready for samples.
     */
    public static function startWriting($path, $kind, $rate)
    {
        $handle = fopen($path, "wb");
        if ($handle === false) {
            throw new \RuntimeException("$path cannot be written");
        }
        $room = ($kind === "wav") ? self::HEADER_BYTES
            : self::AIFF_HEADER_BYTES;
        fwrite($handle, str_repeat("\x00", $room));
        return $handle;
    }
    /**
     * addPiece writes a run of samples to a file already opened by
     * startWriting. Each sample arrives as a fraction of one and is
     * written as a whole number, held at the edge where it goes past
     * what a sample can hold.
     *
     * @param resource $handle The open file.
     * @param array $run The samples to write.
     * @param string $kind The word wav or aiff.
     * @return int How many samples were written.
     */
    public static function addPiece($handle, $run, $kind)
    {
        $wide = ($kind === "wav") ? "v" : "n";
        $written = "";
        foreach ($run as $sample) {
            $value = (int)round($sample * self::FULL_SCALE);
            if ($value > self::FULL_SCALE) {
                $value = self::FULL_SCALE;
            }
            if ($value < -self::FULL_SCALE) {
                $value = -self::FULL_SCALE;
            }
            $written .= pack($wide, $value & 0xFFFF);
        }
        fwrite($handle, $written);
        return count($run);
    }
    /**
     * finishWriting fills in the description at the front of the file
     * now that the length of the sound is known, and closes the file. A
     * player reads that description first, so a file left without it
     * cannot be played.
     *
     * @param resource $handle The open file.
     * @param string $path The file, so its length can be read.
     * @param string $kind The word wav or aiff.
     * @param int $rate How many samples a second the sound runs at.
     * @param int $count How many samples were written.
     */
    public static function finishWriting($handle, $path, $kind, $rate,
        $count)
    {
        $sound_length = $count * self::SAMPLE_BYTES;
        fseek($handle, 0);
        if ($kind === "wav") {
            fwrite($handle, self::wavHeader($rate, $sound_length));
        } else {
            fwrite($handle,
                ("FORM" . pack("N", 46 + $sound_length) . "AIFF" . "COMM" .
                    pack("N", 18) . pack("n", 1) . pack("N", $count)
                        . pack("n", self::SAMPLE_BYTES * 8)
                        . self::wideRate($rate) . "SSND"
                        . pack("N", $sound_length + 8)
                        . pack("N", 0) . pack("N", 0)));
        }
        fclose($handle);
    }
    /**
     * wavHeader builds the description that goes at the front of a WAV
     * file: what the file is, how the sound was recorded, and how many
     * bytes of it follow.
     *
     * @param int $rate How many samples a second the sound runs at.
     * @param int $sound_length How many bytes of sound follow.
     * @return string The description, ready to write.
     */
    public static function wavHeader($rate, $sound_length)
    {
        $bytes_a_second = $rate * self::SAMPLE_BYTES;
        return "RIFF" . pack("V", 36 + $sound_length) . "WAVE"
            . "fmt " . pack("V", 16) . pack("v", 1) . pack("v", 1)
            . pack("V", $rate) . pack("V", $bytes_a_second)
            . pack("v", self::SAMPLE_BYTES)
            . pack("v", self::SAMPLE_BYTES * 8)
            . "data" . pack("V", $sound_length);
    }
    /**
     * wideRate turns a recording rate into the ten byte number an AIFF
     * file writes it as, which is the shape readWideRate reads back.
     *
     * @param int $rate How many samples a second the sound runs at.
     * @return string The ten bytes, ready to write.
     */
    public static function wideRate($rate)
    {
        if ($rate <= 0) {
            return str_repeat("\x00", 10);
        }
        $moved = 0;
        $whole = (float)$rate;
        while ($whole < 9223372036854775808.0 / 2.0) {
            $whole *= 2.0;
            $moved++;
        }
        $held = (int)$whole;
        return pack("n", 16383 + 63 - $moved)
            . pack("N", ($held >> 32) & 0xFFFFFFFF)
            . pack("N", $held & 0xFFFFFFFF);
    }
}
