<?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
 *
 * The audio half of AVTool: reading a recording a browser made, saying
 * what is inside it, and writing it out as a file every browser plays.
 */
namespace seekquarry\yioop\library\av_processing;

/**
 * AudioConverter reads a recording made by a browser and writes it out
 * in a kind every browser plays. A browser records Opus inside an Ogg
 * or a WebM file, which Safari will not play, so a site that keeps
 * voice messages has to turn each recording into an MP4 holding AAC.
 * Yioop calls this when a message is saved, and AVTool calls it from
 * the command line.
 *
 * @author Chris Pollett
 */
class AudioConverter
{
    /**
     * FULL_SCALE is the value a sample takes at the loudest a recording
     * can hold. The decoder hands back whole numbers up to this, and
     * the encoder wants a fraction of one, so each sample is divided by
     * it on the way through.
     * @var int
     */
    /**
     * OPUS_PLAY_RATE is how many samples a second a recording made with
     * the Opus audio codec plays at, whatever rate its sound was
     * recorded at. The standard fixes this.
     */
    const OPUS_PLAY_RATE = 48000;
    const FULL_SCALE = 32768;
    /**
     * SAMPLES_A_PIECE is how many decoded samples are gathered before
     * they go to the encoder. Two seconds of sound at a time keeps the
     * memory a conversion needs flat, whatever the length of the
     * recording.
     * @var int
     */
    const SAMPLES_A_PIECE = 96000;
    /**
     * RECORDED_BITS_PER_SECOND is how many bits a second the written
     * file aims at. Speech at one channel sounds clean at this rate and
     * the file stays small enough to send.
     * @var int
     */
    const RECORDED_BITS_PER_SECOND = 32000;
    /**
     * convert reads one sound file and writes another, choosing what to
     * read and what to write from the bytes of the input and the name
     * of the output. Sound passes through a couple of seconds at a
     * time, so a file of any length is converted without a large file
     * beside it.
     *
     * @param string $path The file to read.
     * @param string $out Where to write the converted sound.
     * @return array How many samples were written under the key
     *     samples, and how long they run under the key seconds.
     */
    public static function convert($path, $out)
    {
        $writing = self::kindWanted($out);
        if ($writing === "") {
            throw new \RuntimeException("a sound file is written as "
                . ".m4a, .mp4, .wav or .aiff");
        }
        $reading = self::readingKind($path);
        /* Sound already compressed the way an MP4 wants it is copied
           across rather than decoded and compressed again, which is
           quicker and loses nothing. */
        if ($writing === "m4a" && $reading === "video") {
            $found = self::soundOfVideo($path);
            if ($found["codec"] === "aac") {
                return self::copySound($found, $out);
            }
        }
        if ($writing === "m4a") {
            return self::toM4a($path, $reading, $out);
        }
        return self::toPlain($path, $out, $writing);
    }
    /**
     * copySound writes the sound track of a video into a file of its
     * own without decoding it. Where the sound is already compressed
     * the way an MP4 holds it, the pieces are carried across as they
     * stand, so nothing is lost and no decoder is needed.
     *
     * @param array $found The sound track, as soundOfVideo gave it.
     * @param string $out Where to write the file.
     * @return array How many samples were written under the key
     *     samples, and how long they run under the key seconds.
     */
    public static function copySound($found, $out)
    {
        if (empty($found["pieces"])) {
            /* A file with no sound in it plays in no browser, and one
               written anyway would replace a recording that at least
               played where it was made. */
            throw new \RuntimeException("no sound was found in that "
                . "recording");
        }
        $rate = self::rateWithin($found["setup"]);
        Mp4Writer::writeCompressed($out, $found["pieces"], $rate,
            $found["channels"]);
        $samples = count($found["pieces"]) * Mp4Writer::FRAME_SAMPLES;
        return ["samples" => $samples,
            "seconds" => round($samples / max(1, $rate), 3)];
    }
    /**
     * rateWithin reads how many samples a second a compressed sound
     * track runs at, out of the settings its file carries. The settings
     * name the rate by its place in a list the standard fixes rather
     * than writing the rate itself.
     *
     * @param string $setup The settings, as the file stored them.
     * @return int How many samples a second, or forty-eight thousand
     *     where the settings do not say.
     */
    public static function rateWithin($setup)
    {
        if (strlen($setup) < 2) {
            return OpusDecoder::SAMPLE_RATE;
        }
        $first = ord($setup[0]);
        $second = ord($setup[1]);
        $named = (($first & 0x07) << 1) | (($second >> 7) & 0x01);
        $listed = Mp4Writer::LISTED_RATES;
        return $listed[$named] ?? OpusDecoder::SAMPLE_RATE;
    }
    /**
     * soundOfVideo hands back the sound track of a video file: the
     * pieces of compressed sound and the name of the codec that
     * compressed them. Somebody who wants the sound of a video would
     * otherwise have to decode its pictures to reach it.
     *
     * @param string $path The video to read.
     * @return array What the sound track holds, keyed by codec, pieces,
     *     channels and setup.
     */
    public static function soundOfVideo($path)
    {
        $kind = SoundTrack::kindOf($path);
        if ($kind === "") {
            throw new \RuntimeException(basename($path) . " is not a "
                . "video file this reads");
        }
        return SoundTrack::fromFile($path, $kind);
    }
    /**
     * readingKind says which kind of sound a file holds, whether it is
     * a recording a browser made or a file that keeps its samples as
     * they are. A caller needs the answer before it can read a single
     * sample.
     *
     * @param string $path The file to look at.
     * @return string The word ogg, webm, wav or aiff.
     */
    public static function readingKind($path)
    {
        $found = self::soundKind($path);
        if ($found !== "") {
            return $found;
        }
        $found = PlainSound::kindOf($path);
        if ($found !== "") {
            return $found;
        }
        /* A video carries its sound beside its pictures, and the sound
           is read out of it the same way a recording is read. */
        $video = SoundTrack::kindOf($path);
        if ($video !== "") {
            return "video";
        }
        throw new \RuntimeException(basename($path) . " is not a sound "
            . "file this reads");
    }
    /**
     * kindWanted says which kind of file a name asks for, from the
     * letters after its last dot. A caller uses it to choose what to
     * write before it reads anything.
     *
     * @param string $out The name of the file to write.
     * @return string The word m4a, wav or aiff, or an empty string
     *     where the name asks for something else.
     */
    public static function kindWanted($out)
    {
        $ending = strtolower(substr($out, strrpos($out, ".") ?: 0));
        if ($ending === ".m4a" || $ending === ".mp4") {
            return "m4a";
        }
        if ($ending === ".wav") {
            return "wav";
        }
        if ($ending === ".aiff" || $ending === ".aif") {
            return "aiff";
        }
        return "";
    }
    /**
     * eachPiece hands back the samples of any sound file this reads, a
     * couple of seconds at a time, as fractions of one. A caller can
     * write them wherever it likes without knowing which kind of file
     * they came out of.
     *
     * @param string $path The file to read.
     * @param string $kind The word ogg, webm, wav or aiff.
     * @return Generator Runs of samples.
     */
    public static function eachPiece($path, $kind)
    {
        if ($kind === "wav" || $kind === "aiff") {
            foreach (PlainSound::eachPiece($path, $kind) as $run) {
                yield $run;
            }
            return;
        }
        /* An Ogg file may carry Vorbis instead of Opus, and the two are
           read by different decoders, so which one is settled by what
           the first packet names itself. */
        if ($kind === "ogg" && SoundTrack::fromOgg($path)["codec"]
            === "vorbis") {
            $read = VorbisDecoder::fromFile($path);
            foreach ($read["decoder"]->eachPacket($read["pieces"])
                as $run) {
                yield $run;
            }
            return;
        }
        if ($kind === "video") {
            $found = self::soundOfVideo($path);
            if ($found["codec"] === "aac") {
                $decoder = new AacDecoder();
                foreach ($found["pieces"] as $piece) {
                    $run = $decoder->decodeFrame($piece);
                    yield $run;
                }
                return;
            }
            if ($found["codec"] !== "opus") {
                throw new \RuntimeException("the sound of this video is "
                    . $found["codec"] . ", which is not decoded yet");
            }
            $read = ["pieces" => $found["pieces"], "header" => null];
            $channels = $found["channels"];
        } else {
            $read = self::packetsOf($path, $kind);
            $channels = ($read["header"] !== null) ?
                $read["header"]->channel_count : 1;
        }
        $stretches = [];
        foreach ($read["pieces"] as $piece) {
            try {
                $sound = OpusPacket::fromString($piece);
            } catch (\Exception $trouble) {
                continue;
            }
            if ($sound->method != OpusPacket::MUSIC_METHOD) {
                /* A browser records a voice the way built for speech,
                   which a different decoder reads. The whole file goes
                   to that decoder rather than this loop, since it keeps
                   what one stretch leaves the next. */
                foreach (self::speechOf($path, $read["header"],
                    $read["pieces"]) as $run) {
                    yield $run;
                }
                return;
            }
            foreach ($sound->stretches as $stretch) {
                if (strlen($stretch) >= 2) {
                    $stretches[] = $stretch;
                }
            }
        }
        $waiting = [];
        foreach (OpusDecoder::eachStretch($stretches, $channels)
            as $settled) {
            foreach ($settled as $sample) {
                $waiting[] = self::holdInRange($sample /
                    self::FULL_SCALE);
            }
            if (count($waiting) >= self::SAMPLES_A_PIECE) {
                yield $waiting;
                $waiting = [];
            }
        }
        if ($waiting !== []) {
            yield $waiting;
        }
    }
    /**
     * toPlain writes a sound file that keeps its samples as they are,
     * reading whatever kind of file it was given a couple of seconds at
     * a time. A WAV or an AIFF plays anywhere and can be edited, where
     * the compressed kinds cannot.
     *
     * @param string $path The file to read.
     * @param string $out Where to write the file.
     * @param string $writing The word wav or aiff.
     * @return array How many samples were written under the key
     *     samples, and how long they run under the key seconds.
     */
    public static function toPlain($path, $out, $writing)
    {
        $reading = self::readingKind($path);
        $rate = OpusDecoder::SAMPLE_RATE;
        if ($reading === "wav" || $reading === "aiff") {
            $said = PlainSound::readHeader($path, $reading);
            $rate = max(1, $said["rate"]);
        }
        $handle = PlainSound::startWriting($out, $writing, $rate);
        $written = 0;
        foreach (self::eachPiece($path, $reading) as $run) {
            $written += PlainSound::addPiece($handle, $run, $writing);
        }
        if ($written < 1) {
            throw new \RuntimeException("no sound was found in that "
                . "recording");
        }
        PlainSound::finishWriting($handle, $out, $writing, $rate,
            $written);
        return ["samples" => $written,
            "seconds" => round($written / $rate, 3)];
    }
    /**
     * soundKind says which kind of recording a file holds, reading the
     * first bytes rather than trusting the name. A caller uses it to
     * decide whether a file is a recording at all before opening it.
     *
     * @param string $path The file to look at.
     * @return string The word ogg or webm, or an empty string where the
     *     file is neither.
     */
    public static function soundKind($path)
    {
        $handle = @fopen($path, "rb");
        if ($handle === false) {
            return "";
        }
        $head = fread($handle, 4);
        fclose($handle);
        if ($head === "OggS") {
            return "ogg";
        }
        if ($head === "\x1A\x45\xDF\xA3") {
            return "webm";
        }
        return "";
    }
    /**
     * packetsOf reads every packet of compressed sound out of a
     * recording, along with what the recording says about itself. A
     * caller needs both before it can decode anything.
     *
     * @param string $path The recording to read.
     * @param string $kind The word ogg or webm, as soundKind gave it.
     * @return array The packets under the key pieces, and the
     *     recording's own description under the key header.
     */
    public static function packetsOf($path, $kind)
    {
        $pieces = [];
        $header = null;

        if ($kind == "ogg") {
            $reader = OggDemuxer::fromName($path);
            $seen = 0;
            foreach ($reader->packets() as $piece) {
                $seen++;
                if ($seen == 1) {
                    $header = OpusHeader::fromString($piece->data);
                    continue;
                }
                if ($seen == 2) {
                    continue;
                }
                $pieces[] = $piece->data;
            }
        } else {
            $reader = WebmDemuxer::fromName($path);
            foreach ($reader->packets() as $piece) {
                $pieces[] = $piece->data;
            }
            if ($reader->codec_setup !== "") {
                $header = OpusHeader::fromString($reader->codec_setup);
            }
        }
        return ["pieces" => $pieces, "header" => $header];
    }
    /**
     * describe says what a recording holds: how it is stored, how many
     * packets of sound it carries, how long it runs and how many
     * channels it was recorded in. A caller prints this when somebody
     * asks what is inside a file.
     *
     * @param string $path The recording to look at.
     * @param string $kind The word ogg or webm, as soundKind gave it.
     * @return array What the recording says about itself, keyed by
     *     container, packets, seconds and channels.
     */
    public static function describe($path, $kind)
    {
        if ($kind === "ogg") {
            $found = SoundTrack::fromOgg($path);
            if ($found["codec"] === "vorbis") {
                $said = VorbisHeader::fromString(
                    OggDemuxer::fromName($path)->packets()
                    ->current()->data);
                return ["container" => "ogg", "codec" => "vorbis",
                    "packets" => count($found["pieces"]),
                    "rate" => $said->rate,
                    "channels" => $said->channels];
            }
        }
        $read = self::packetsOf($path, $kind);
        $seconds = 0.0;
        foreach ($read["pieces"] as $piece) {
            try {
                $sound = OpusPacket::fromString($piece);
            } catch (\Exception $trouble) {
                continue;
            }
            $seconds += $sound->duration() / 1000.0;
        }
        return ["container" => $kind,
            "packets" => count($read["pieces"]),
            "seconds" => round($seconds, 3),
            "channels" => ($read["header"] !== null) ?
                $read["header"]->channel_count : 1];
    }
    /**
     * toM4a turns a recording into an MP4 file holding AAC, which every
     * browser plays. The sound is read a couple of seconds at a time:
     * each piece is decoded, handed to the encoder, and dropped, so a
     * recording of any length is converted without a large file beside
     * it and without holding the whole sound in memory.
     *
     * The samples keep the loudness the recording was made at. Anything
     * past what a sample can hold is held at the edge, which a
     * recording made by a browser never reaches.
     *
     * @param string $path The recording to read.
     * @param string $kind The word ogg or webm, as soundKind gave it.
     * @param string $out Where to write the MP4 file.
     * @return array How many samples were written under the key
     *     samples, and how long they run under the key seconds.
     */
    public static function toM4a($path, $kind, $out)
    {
        $encoder = new AacEncoder(self::RECORDED_BITS_PER_SECOND);
        $written = 0;
        foreach (self::eachPiece($path, $kind) as $run) {
            $encoder->take($run);
            $written += count($run);
        }
        $encoder->finish();
        if ($written < 1 || $encoder->frames === []) {
            /* A file with no sound in it plays in no browser, and one
               written anyway would replace a recording that at least
               played where it was made. */
            throw new \RuntimeException("no sound was found in that "
                . "recording");
        }
        Mp4Writer::writeCompressed($out, $encoder->frames,
            OpusDecoder::SAMPLE_RATE, 1);
        return ["samples" => $written,
            "seconds" => round($written / OpusDecoder::SAMPLE_RATE, 3)];
    }
    /**
     * speechOf gives the samples of a recording made the way built for
     * speech, at the rate the file says it holds. A browser records a
     * voice message this way, so this is the path a message takes when
     * a wiki page saves it.
     *
     * @param string $path the file holding the recording
     * @param object $header what the file says about itself, or null
     *     where it says nothing; its lead in says how many samples to
     *     drop from the front
     * @param array $pieces the recording's packets where the caller has
     *     already taken them out of the file, or null to open the file
     *     here; a recording held in a WebM file comes this way, since
     *     the speech decoder opens only Ogg files itself
     * @return \Generator runs of samples, each between minus one and
     *     one
     */
    public static function speechOf($path, $header = null,
        $pieces = null)
    {
        /* The packets are handed over where the caller has them, since
           a recording made by a browser may sit in a WebM file, which
           the speech decoder does not open for itself. */
        $dropping = ($header !== null) ?
            intdiv($header->lead_in, intdiv(SpeechDecoder::HEADER_RATE,
            SpeechDecoder::SAMPLE_RATE)) : 0;
        $samples = ($pieces === null) ?
            SpeechDecoder::samplesOfRecording($path) :
            SpeechDecoder::samplesOfPackets($pieces, $dropping);
        /* Opus always plays at forty-eight thousand samples a second
           whatever rate the sound was recorded at, so that is the rate
           the samples are raised to. */
        $wanted = self::OPUS_PLAY_RATE;
        $samples = SpeechDecoder::raisedToRate($samples,
            SpeechDecoder::SAMPLE_RATE, $wanted);
        $waiting = [];
        foreach ($samples as $one) {
            $waiting[] = self::holdInRange($one / self::FULL_SCALE);
            if (count($waiting) >= self::SAMPLES_A_PIECE) {
                yield $waiting;
                $waiting = [];
            }
        }
        if ($waiting !== []) {
            yield $waiting;
        }
    }
    /**
     * holdInRange keeps a sample within the range the encoder works in,
     * which runs from one below zero to one above it. A recording made
     * loud can decode a little past that edge, and a value past the
     * edge would wrap round to the opposite sign when written.
     *
     * @param float $sample One decoded sample, already divided by
     *     FULL_SCALE.
     * @return float The sample, held at the edge where it went past.
     */
    public static function holdInRange($sample)
    {
        if ($sample > 1.0) {
            return 1.0;
        }
        if ($sample < -1.0) {
            return -1.0;
        }
        return $sample;
    }
}
