From 126e2cd233248dad282660bb397aae9f5ed20402 Mon Sep 17 00:00:00 2001 From: TheM14 Date: Sun, 18 Oct 2026 21:31:38 +0800 Subject: [PATCH] Init mpv-joc --- .github/workflows/build.yml | 83 + .github/workflows/drift.yml | 22 + .gitignore | 17 + CMakeLists.txt | 50 + LICENSE | 21 + LICENSE-mpv | 501 ++++++ README.en.md | 221 +++ README.md | 222 +++ THIRD_PARTY_NOTICES.md | 45 + config/cplugin-mpv.conf.example | 25 + fork/README.md | 230 +++ fork/docs/android.md | 64 + fork/files/audio/decode/ad_joc.c | 875 +++++++++++ fork/files/audio/decode/ad_joc.h | 27 + fork/files/audio/decode/joc_core.h | 492 ++++++ fork/files/audio/decode/joc_eac3.c | 100 ++ fork/files/audio/decode/joc_eac3.h | 40 + fork/files/audio/decode/joc_stream.h | 146 ++ fork/files/audio/decode/joc_version.h | 16 + fork/mpv.conf.example | 28 + fork/patches/mpv-ad-joc.patch | 136 ++ fork/tools/apply_edits.py | 177 +++ fork/tools/build_fork.ps1 | 62 + fork/tools/bundle_dlls.sh | 31 + src/container_scan.cpp | 544 +++++++ src/container_scan.h | 47 + src/cplugin_main.cpp | 570 +++++++ src/eac3_scan.cpp | 453 ++++++ src/eac3_scan.h | 83 + src/joc_decode.cpp | 1472 ++++++++++++++++++ src/joc_decode.h | 206 +++ src/log.cpp | 169 ++ src/log.h | 46 + src/plugin/audio_source.cpp | 130 ++ src/plugin/audio_source.h | 58 + src/plugin/config.cpp | 150 ++ src/plugin/config.h | 56 + src/plugin/http_server.cpp | 222 +++ src/plugin/http_server.h | 66 + src/plugin/wav.cpp | 116 ++ src/plugin/wav.h | 19 + src/win_path.h | 90 ++ third_party/joc/include/joc_core.h | 492 ++++++ third_party/joc/include/joc_stream.h | 146 ++ third_party/joc/include/joc_version.h | 16 + third_party/mpv/client.h | 2033 +++++++++++++++++++++++++ tools/build.ps1 | 46 + tools/compare_wav.py | 39 + tools/fetch.py | 12 + tools/install.ps1 | 32 + tools/verify_kernel.ps1 | 21 + tools/verify_parity.ps1 | 70 + 52 files changed, 11035 insertions(+) create mode 100644 .github/workflows/build.yml create mode 100644 .github/workflows/drift.yml create mode 100644 .gitignore create mode 100644 CMakeLists.txt create mode 100644 LICENSE create mode 100644 LICENSE-mpv create mode 100644 README.en.md create mode 100644 README.md create mode 100644 THIRD_PARTY_NOTICES.md create mode 100644 config/cplugin-mpv.conf.example create mode 100644 fork/README.md create mode 100644 fork/docs/android.md create mode 100644 fork/files/audio/decode/ad_joc.c create mode 100644 fork/files/audio/decode/ad_joc.h create mode 100644 fork/files/audio/decode/joc_core.h create mode 100644 fork/files/audio/decode/joc_eac3.c create mode 100644 fork/files/audio/decode/joc_eac3.h create mode 100644 fork/files/audio/decode/joc_stream.h create mode 100644 fork/files/audio/decode/joc_version.h create mode 100644 fork/mpv.conf.example create mode 100644 fork/patches/mpv-ad-joc.patch create mode 100644 fork/tools/apply_edits.py create mode 100644 fork/tools/build_fork.ps1 create mode 100644 fork/tools/bundle_dlls.sh create mode 100644 src/container_scan.cpp create mode 100644 src/container_scan.h create mode 100644 src/cplugin_main.cpp create mode 100644 src/eac3_scan.cpp create mode 100644 src/eac3_scan.h create mode 100644 src/joc_decode.cpp create mode 100644 src/joc_decode.h create mode 100644 src/log.cpp create mode 100644 src/log.h create mode 100644 src/plugin/audio_source.cpp create mode 100644 src/plugin/audio_source.h create mode 100644 src/plugin/config.cpp create mode 100644 src/plugin/config.h create mode 100644 src/plugin/http_server.cpp create mode 100644 src/plugin/http_server.h create mode 100644 src/plugin/wav.cpp create mode 100644 src/plugin/wav.h create mode 100644 src/win_path.h create mode 100644 third_party/joc/include/joc_core.h create mode 100644 third_party/joc/include/joc_stream.h create mode 100644 third_party/joc/include/joc_version.h create mode 100644 third_party/mpv/client.h create mode 100644 tools/build.ps1 create mode 100644 tools/compare_wav.py create mode 100644 tools/fetch.py create mode 100644 tools/install.ps1 create mode 100644 tools/verify_kernel.ps1 create mode 100644 tools/verify_parity.ps1 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..94e227b --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,83 @@ +name: build + +on: + workflow_dispatch: + inputs: + mpv_ref: + description: mpv branch, tag or commit + default: master + push: + tags: ["v*"] + +jobs: + windows: + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + + - uses: msys2/setup-msys2@v2 + with: + msystem: MINGW64 + update: true + install: >- + mingw-w64-x86_64-gcc + mingw-w64-x86_64-meson + mingw-w64-x86_64-ninja + mingw-w64-x86_64-pkgconf + mingw-w64-x86_64-ffmpeg + mingw-w64-x86_64-luajit + + - name: Clone mpv + shell: pwsh + run: | + $ref = "${ github.event.inputs.mpv_ref }}" + if (-not $ref) { $ref = "master" } + git clone --depth 1 --branch $ref https://github.com/mpv-player/mpv.git mpv + git -C mpv log -1 --format='%h %cd %s' --date=short + + - name: Apply ad_joc + shell: pwsh + run: | + Copy-Item fork/files/audio/decode/* mpv/audio/decode/ -Force + python fork/tools/apply_edits.py mpv + + - name: Build joc_core + shell: pwsh + run: | + git clone --depth 1 https://github.com/TheM14/JustOneCacophony.git joc + cmake -S joc -B joc/build -A x64 + cmake --build joc/build --config Release + $lib = Get-ChildItem joc/build -Recurse -Filter joc_core.lib | Select-Object -First 1 + if (-not $lib) { throw "joc_core.lib not found" } + "JOC_CORE_DIR=$($lib.DirectoryName)" | Out-File -Append $env:GITHUB_ENV + + - name: Build mpv + shell: pwsh + run: | + $bash = "C:\msys64\usr\bin\bash.exe" + $dir = (Resolve-Path mpv).Path -replace '\\','/' + $core = $env:JOC_CORE_DIR -replace '\\','/' + $lines = @( + 'set -e', + 'export PATH=/mingw64/bin:/usr/bin:$PATH', + 'export MSYSTEM=MINGW64', + "cd $dir", + "meson setup build --buildtype=release -Dgpl=false -Dlua=luajit -Djoc-core-dir=$core", + 'ninja -C build' + ) + ($lines -join [Environment]::NewLine) | & $bash -lc "cat > /tmp/b.sh && bash /tmp/b.sh" + + - name: Bundle + shell: pwsh + run: | + $bash = "C:\msys64\usr\bin\bash.exe" + $dir = (Resolve-Path mpv).Path -replace '\\','/' + & $bash -lc "$env:GITHUB_WORKSPACE/fork/tools/bundle_dlls.sh '$dir/build'" + Copy-Item (Join-Path $env:JOC_CORE_DIR "joc_core.dll") mpv/build -Force + Copy-Item fork/mpv.conf.example mpv/build -Force + Compress-Archive -Path mpv/build/* -DestinationPath mpv-ad-joc.zip + + - uses: actions/upload-artifact@v4 + with: + name: mpv-ad-joc-windows + path: mpv-ad-joc.zip diff --git a/.github/workflows/drift.yml b/.github/workflows/drift.yml new file mode 100644 index 0000000..3dc1c07 --- /dev/null +++ b/.github/workflows/drift.yml @@ -0,0 +1,22 @@ +name: drift + +# Checks that the integration still applies to the latest mpv, so a broken +# anchor is noticed before a release build is attempted. +on: + schedule: + - cron: "0 3 * * *" + workflow_dispatch: + +jobs: + latest-mpv: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Clone latest mpv + run: | + git clone --depth 1 https://github.com/mpv-player/mpv.git mpv + git -C mpv log -1 --format='%h %cd %s' --date=short + - name: Apply ad_joc + run: | + cp fork/files/audio/decode/* mpv/audio/decode/ + python3 fork/tools/apply_edits.py mpv diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..55eb52f --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +build/ +out/ +dist/ +*.log +*.log.1 +*.zip +*.wav +HRTF/ +*.sofa +*.jochrtf +*.personalized_headphone +joc-hrtf-cache/ +.vs/ +*.user +__pycache__/ +*.pyc +_parity/ diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..b35054e --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,50 @@ +cmake_minimum_required(VERSION 3.21) +project(joc_mpv CXX) + +# joc_mpv is an mpv C plugin (cplugins feature) that plays E-AC-3 JOC with the +# JustOneCacophony renderer. The renderer itself is joc_core.dll, which this +# project can build from a JustOneCacophonyCXX checkout so the kernel stays the +# byte-identical artifact both frontends share. + +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$:Debug>") + +set(JOC_CORE_SOURCE "" CACHE PATH "JustOneCacophonyCXX checkout to build joc_core.dll from") + +add_library(joc_mpv SHARED + src/cplugin_main.cpp + src/joc_decode.cpp + src/container_scan.cpp + src/eac3_scan.cpp + src/log.cpp + src/plugin/audio_source.cpp + src/plugin/config.cpp + src/plugin/http_server.cpp + src/plugin/wav.cpp +) +target_include_directories(joc_mpv PRIVATE + src + third_party + third_party/joc/include +) +target_compile_definitions(joc_mpv PRIVATE + NOMINMAX + WIN32_LEAN_AND_MEAN + _CRT_SECURE_NO_WARNINGS + UNICODE + _UNICODE +) +target_compile_options(joc_mpv PRIVATE /W4 /permissive- /utf-8 /EHsc /fp:precise) +target_link_libraries(joc_mpv PRIVATE ws2_32) +set_target_properties(joc_mpv PROPERTIES PREFIX "" OUTPUT_NAME "joc_mpv") + +if(JOC_CORE_SOURCE) + set(JOC_BUILD_TESTS OFF CACHE BOOL "" FORCE) + set(JOC_BUILD_DEVTOOLS OFF CACHE BOOL "" FORCE) + add_subdirectory("${JOC_CORE_SOURCE}" "${CMAKE_BINARY_DIR}/joc_core") + add_custom_command(TARGET joc_mpv POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy_if_different + $ $/joc_core.dll + COMMENT "Copying joc_core.dll next to joc_mpv.dll") +endif() diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..676e3b7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 TheM14 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/LICENSE-mpv b/LICENSE-mpv new file mode 100644 index 0000000..d35234e --- /dev/null +++ b/LICENSE-mpv @@ -0,0 +1,501 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence + the version number 2.1.] + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software packages--typically libraries--of the +Free Software Foundation and other authors who decide to use it. You +can use it too, but we suggest you first think carefully about whether +this license or the ordinary General Public License is the better +strategy to use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of +it in new free programs; and that you are informed that you can do +these things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does Less to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License Agreement applies to any software library or other +program which contains a notice placed by the copyright holder or +other authorized party saying it may be distributed under the terms of +this Lesser General Public License (also called "this License"). +Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".) + + "Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + + 1. You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + + 2. You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) The modified work must itself be a software library. + + b) You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c) You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d) If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure that, + in the event an application does not supply such function or + table, the facility still operates, and performs whatever part of + its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a "work that uses the Library". Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or +link a "work that uses the Library" with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + + a) Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that + uses the Library", as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + + b) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a + copy of the library already present on the user's computer system, + rather than copying library functions into the executable, and (2) + will operate properly with a modified version of the library, if + the user installs one, as long as the modified version is + interface-compatible with the version that the work was made with. + + c) Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + + d) If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + + e) Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies +the executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + + 7. You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + + a) Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b) Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + + 8. You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + 9. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + + 11. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + + 13. The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + + NO WARRANTY + + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library 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 + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, see . + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the library, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the + library `Frob' (a library for tweaking knobs) written by James Random Hacker. + + , 1 April 1990 + Moe Ghoul, President of Vice + +That's all there is to it! diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..5aeb33a --- /dev/null +++ b/README.en.md @@ -0,0 +1,221 @@ +# mpv-joc — E-AC-3 JOC (Dolby Atmos) playback for mpv + +An mpv C plugin (cplugins feature). It takes the object audio out of an E-AC-3 +JOC stream, rebuilds it with the [JustOneCacophony](https://github.com/TheM14/JustOneCacophony) +renderer, and hands the result to mpv as an ordinary audio track. The renderer, +the engine and the settings are the same ones the upstream frontends +the upstream project's command-line frontend uses, so the samples delivered to the player +are **bit-identical**. + +* Output: binaural (HRTF) or a 2.0 – 7.1 speaker layout; +* Output device: mpv's own audio output, i.e. WASAPI on Windows (optionally + forced, optionally exclusive); +* Configuration: mpv's own configuration file, with one `joc-*` option namespace; +* Input: bare `.eac3` / `.ec3`, or the E-AC-3 JOC track of an MP4 / Matroska file + (a video track keeps playing normally); +* Seeking: mpv's seek works; the renderer re-enters the bitstream at the target. + +## License + +This repository (plugin, patch, scripts, documentation) is **MIT**, see [LICENSE](LICENSE). + +The code under `fork/` is compiled into mpv, so distributing the resulting player is also +subject to mpv's own license: LGPL-2.1-or-later (GPL-2.0-or-later when built with +`-Dgpl=true`). mpv's license text ships with this repository as [LICENSE-mpv](LICENSE-mpv). +The `joc_core` renderer is not distributed here; see +[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). + +## Relationship to the upstream project + +This repository contains the **mpv-side integration only**: the cplugin (`src/`) and the +ad_joc patch (`fork/`). The object-audio renderer, E-AC-3/EMDF parsing, SOFA and Rosella +support come from [TheM14/JustOneCacophony](https://github.com/TheM14/JustOneCacophony); the behaviour reference is +the upstream project's `joc_cli` (the comparison basis). `joc_core.dll` is not distributed here — it is built from +the upstream project, and none of its code is copied or modified in this repository. + +## Repository layout + +One renderer (`joc_core.dll`), two integration shapes: + +| Shape | Where | mpv requirement | +|---|---|---| +| **cplugin**: drop-in for stock mpv | `src/` `config/` `tools/` | built with cplugins | +| **ad_joc patch**: compile the decoder into mpv | `fork/` | build mpv from source (see [fork/README.md](fork/README.md)) | + +## Requirements + +* mpv with **cplugins** support (official Windows builds have it; check + `List of enabled features` in `mpv --msg-level=all=v`). +* An `ffmpeg` executable (found on `PATH` by default, `joc-ffmpeg` overrides). +* HRTF data for binaural output: a SOFA measurement set or a Rosella + `.personalized_headphone` model. **Not bundled**; speaker layouts do not need it. + +## Install + +```text +\\scripts\\joc_mpv.dll the plugin +\\joc_core.dll the renderer (same binary as JustOneCacophonyCXX) +\\HRTF\\binaural.sofa default binaural data +\\HRTF\\binaural.personalized_headphone (Rosella model, either one) +``` + +`joc_core.dll` must not go into `scripts\\`: mpv offers every file in that +directory to the script loader. The plugin looks for the renderer at `joc-core`, +then `\\joc_core.dll`, then `\\..\\joc_core.dll`, then `PATH`. + +Add to `mpv.conf`: + +```ini +script-opts=joc-output=binaural,joc-hrtf-source=sofa +``` + +Or load it explicitly: + +```powershell +mpv --script="C:\\path\\to\\joc_mpv.dll" --script-opts=joc-output=speaker,joc-layout=7.1 movie.mkv +``` + +## Options + +All keys live in mpv's `--script-opts`, prefixed `joc-`; unknown keys are +ignored and reported in `joc_decoder.log`. + +| Key | Values | Default | Meaning | +|---|---|---|---| +| `joc-enabled` | yes / no | yes | disable the plugin entirely | +| `joc-output` | binaural / speaker | binaural | output form | +| `joc-layout` | 2.0 3.1 5.1 7.1 5.1.2 5.1.4 7.1.2 7.1.4 9.1.4 9.1.6 | 7.1 | speaker layout | +| `joc-hrtf-source` | sofa / rosella | sofa | binaural HRTF input | +| `joc-hrtf` | path | empty | empty: default name under `\\HRTF\\` or `\\..\\HRTF\\` | +| `joc-mode` | near / mid / far | mid | binaural mode | +| `joc-gain-db` | float (dB) | 0 | render gain (binaural can exceed full scale) | +| `joc-tail` | seconds | 5.0 | binaural room tail cap (never delivered as playback time) | +| `joc-int24` | yes / no | no | deliver 24-bit fixed point instead of float32 | +| `joc-object-delay` | samples | 1473 | OAMD object delay, matching the existing implementation | +| `joc-threads` | integer | 0 | kernel threads, 0 = automatic | +| `joc-ffmpeg` | path | ffmpeg | ffmpeg used for the core PCM | +| `joc-core` | path | empty | explicit `joc_core.dll` | +| `joc-wasapi` | auto / yes / no | auto | `yes` sets `ao=wasapi` | +| `joc-exclusive` | yes / no | no | sets `audio-exclusive=yes` | +| `joc-chunk` | seconds | 2.0 | audio bytes written per HTTP chunk | +| `joc-mute-until-ready` | yes / no | yes | silence the file's own track until the rendered one is selected | +| `joc-hrtf-cache` | auto / memory / disk / none | auto | compiled-HRTF cache; auto = `\\joc-hrtf-cache` | +| `joc-hrtf-cache-dir` | path | empty | explicit cache directory | +| `joc-attach` | yes / no | yes | no: serve the stream without adding the track (capture/verification) | +| `joc-verbose` | yes / no | no | log every HTTP request and reposition | +| `joc-log` | path | empty | log file; empty: `\\joc_decoder.log` | + +Layouts wider than 7.1 cannot reach a WASAPI endpoint (8 channels maximum), so +`9.1.4` / `9.1.6` are delivered without a channel mask and will normally not map +correctly; use `7.1.4` or below. + +## How it works + +```text +mpv — video and subtitles as usual + │ + └─ file-loaded ─► probe (bare stream walked directly; container: ask ffmpeg which + track is E-AC-3 and whether it carries JOC) + │ + ▼ + joc_core.dll (joc_stream.h) + ▲ E-AC-3 syncframes + core PCM from ffmpeg + │ + ┌───────────┴────────────┐ + │ rendered as WAV (float32 / int24, with a channel mask) + │ served by an in-process loopback HTTP endpoint with Range support + └───────────┬────────────┘ + ▼ + mpv: audio-add http://127.0.0.1:/joc.wav select +``` + +mpv reads the track as a seekable WAV file, so its demuxer, cache, A/V sync, +WASAPI output and seeking all work unmodified. + +Startup: at `start-file` the plugin probes and creates the renderer while mpv is +still opening the file, and silences the file's own track; at `file-loaded` it +`audio-add ... select`s the rendered track and restores the previous mute state. +Inputs the probe rejects are unmuted immediately (a container whose E-AC-3 track +turns out not to be JOC spends the ~100 ms ffmpeg probe muted; set +`joc-mute-until-ready=no` to disable the behaviour). Measured on a 30 s 7.1.4 clip: +about 0.6 s cold, about 0.37 s once the compiled HRTF is cached. That window is +silence rather than the plain bed, and mpv pauses the audio clock across the +switch, so no content is skipped. The plugin only repositions the +renderer when the requested byte offset differs from the current position, using +the component's seek policy (target frame minus 64 pre-roll frames, then the +output before the target is dropped). + +A seek differs from a from-start render only by a very low noise floor (below +−65 dBFS in measurement); the position itself does not drift. + +## Relationship to the fork approach + +The established solution in this space takes the other path: `mpv-omniphony` is a +**fork of mpv** that adds a `--ad=orender` module, handing demuxed access units to +`liborender`; the codec decoding itself lives in dynamically loaded bridge DLLs +(`harletty_dolby_bridge.dll` and friends, E-AC-3 JOC included). That gives a native +track: no extra track, no startup switch, correct codec information. + +This plugin deliberately stays on stock mpv (cplugins) and pays for it with a +0.3–0.6 s preparation window at startup and an external PCM track (shown as +pcm_f32le). When the native behaviour is required, the right move is an `ad_joc` +module in mpv, built the way mpv-omniphony does it: mpv's AD layer receives +AVPackets, so FFmpeg does not have to change and the renderer stays `joc_core.dll`. +A working prototype of that route — patch against mpv master (2026-10-17), new +sources and build instructions — lives in [`fork/`](fork/README.md); its +`--ad=joc` output was measured bit-identical to `joc_cli` for both binaural and +7.1. The cost is maintaining your own mpv build (MSYS2/MinGW on Windows). + +## Verification + +`tools/verify_parity.ps1` renders a reference WAV with `joc_cli`, fetches what the +plugin actually delivers, and compares the bytes. On this machine (mpv v0.41.0, +FFmpeg 8.0, a 30 s 7.1.4 JOC clip): + +| Case | Result | +|---|---| +| binaural float32 (SOFA) | 1,440,768 samples bit-identical | +| binaural int24 (Rosella) | 1,440,768 samples bit-identical | +| speaker 7.1 float32 | 1,440,768 samples bit-identical | + +The reference is longer only by the binaural room tail: the component and this +plugin cut the delivered stream at the file's duration, `joc_cli`'s +`--binaural-output` does not. + +## Build + +Needs a JustOneCacophonyCXX checkout (for its `joc_core` target): + +```powershell +pwsh -File tools/build.ps1 -JocCoreSource C:\\path\\to\\JustOneCacophonyCXX +``` + +The plugin lands in `build\\Release\\joc_mpv.dll` with `joc_core.dll` beside it. +Plugin only, against an existing `joc_core.dll`: + +```powershell +cmake -S . -B build -G "Visual Studio 17 2022" -A x64 +cmake --build build --config Release +``` + +`/fp:precise` and a static CRT are fixed: the floating-point behaviour is part of +the byte-exact acceptance. + +## Troubleshooting + +`joc_decoder.log` is written to mpv's configuration directory (next to +`mpv.conf`), together with `joc_ffmpeg_*.log`; it cannot live in `scripts\\` +because mpv would try to load it as a script. `--msg-level=all=info` shows the +`JOC: ...` status line. + +* **No JOC message, just plain E-AC-3** — the file has no JOC metadata, or the + container's audio track is not E-AC-3; mpv keeps playing the original track. +* **"cannot find the HRTF file"** — put `binaural.sofa` in `\\HRTF\\` or + point `joc-hrtf` at it. +* **Which track is in use?** — `joc-verbose=yes` and read the `probe:` / `start:` + lines. + +## License + +MIT, see `LICENSE`. The renderer comes from JustOneCacophonyCXX and the decode +engine from the upstream project's frontend code; see `THIRD_PARTY_NOTICES.md`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..e0733b3 --- /dev/null +++ b/README.md @@ -0,0 +1,222 @@ +# mpv-joc — mpv 的 E-AC-3 JOC(Dolby Atmos)播放插件 + +mpv C 插件(cplugins)。它把 E-AC-3 JOC 码流里的对象音频交给 +[JustOneCacophony](https://github.com/TheM14/JustOneCacophony) 的渲染内核重建,再作为一条普通的音频轨 +交给 mpv 播放。渲染走的是与上游前端 +上游项目的命令行前端相同的引擎、相同的设置、相同的 `joc_core.dll`, +因此同一个文件在两个前端上得到的采样**逐字节一致**。 + +- 输出:双耳(HRTF)或 2.0 – 7.1 的扬声器布局; +- 输出设备:照常走 mpv 的音频输出,Windows 上即 WASAPI(可强制 `ao=wasapi`、可开独占); +- 配置:mpv 自己的配置文件,新增 `joc-*` 这一个选项命名空间(见下); +- 输入:裸流 `.eac3` / `.ec3`,或 MP4 / Matroska 里的 E-AC-3 JOC 轨(有视频也照常播); +- 拖放/跳转:mpv 的 seek 正常可用,跳转按目标采样重新进入码流。 + +## 许可 + +本仓库(插件、补丁、脚本、文档)采用 **MIT**,见 [LICENSE](LICENSE)。 + +`fork/` 的代码会编译进 mpv,所以最终播放器的分发还受 mpv 自身许可约束: +LGPL-2.1-or-later(用 `-Dgpl=true` 构建时为 GPL-2.0-or-later)。mpv 的许可全文随仓库 +提供,见 [LICENSE-mpv](LICENSE-mpv)。渲染内核 `joc_core` 不在本仓库分发,其许可见 +[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 + +## 与上游项目的关系 + +本仓库只包含 **mpv 侧的接入代码**:cplugin(`src/`)和 ad_joc 补丁(`fork/`)。 + +- 对象音频的渲染内核、E-AC-3/EMDF 解析、SOFA 与 Rosella 支持来自 + [TheM14/JustOneCacophony](https://github.com/TheM14/JustOneCacophony); +- 行为基准(设置、跳转、逐字节一致的对比对象)是 + 上游项目自带的命令行前端 `joc_cli`(对比基准); +- `joc_core.dll` 不在本仓库分发,由上游构建;这里不含、也不改写内核代码。 + +## 仓库结构 + +同一个渲染内核(`joc_core.dll`)有两种接法,按是否需要自建 mpv 选一个: + +| 形态 | 位置 | 对 mpv 的要求 | +|---|---|---| +| **cplugin**:官方构建即插即用 | `src/` `config/` `tools/` | 带 cplugins(官方 Windows 构建默认有) | +| **ad_joc 补丁**:把解码器编进 mpv | `fork/` | 从 mpv 源码构建,见 [fork/README.md](fork/README.md) | + +```text +mpv-joc/ + src/ cplugin 源码(C++) + config/ 插件配置示例(cplugin-mpv.conf.example) + tools/ 插件构建 / 安装 / 一致性校验脚本 + third_party/ mpv 客户端头、joc 公共头 + fork/ ad_joc 补丁仓库 + files/audio/decode/ 新增的解码器与 E-AC-3 帧工具 + patches/ 同一改动的 diff(精确复现用) + tools/ 锚点应用、构建、DLL 收集脚本 + docs/ Android(libmpv.so)可行性调研 + .github/workflows/ 补丁的 CI:构建产物 + 每日跟最新 mpv 检查 +``` + +## 环境要求 + +* mpv 需要带 **cplugins** 支持。官方 Windows 构建默认开启(`mpv --msg-level=all=v` + 的 `List of enabled features` 里能看到 `cplugins`)。 +* 一个 `ffmpeg` 可执行文件(默认从 `PATH` 找,`joc-ffmpeg` 可以指定)。 +* 双耳输出需要 HRTF 数据:SOFA 测量集,或 Rosella `.personalized_headphone` 模型。 + **本仓库不附带**;扬声器布局不需要。 + +## 安装 + +把三个东西放到 mpv 的目录里(便携版就是 mpv.exe 所在目录): + +```text +\\scripts\\joc_mpv.dll 插件本体 +\\joc_core.dll 渲染内核(与 JustOneCacophonyCXX 同一个二进制) +\\HRTF\\binaural.sofa 双耳渲染默认数据 +\\HRTF\\binaural.personalized_headphone (Rosella 模型,二选一) +``` + +`joc_core.dll` 不能放进 `scripts\\`:mpv 会把该目录下的每个 `.dll` 都当插件加载, +内核会被当成一个没有入口的插件而报错。插件自己的查找顺序是 +`joc-core` 配置 → `<插件目录>\\joc_core.dll` → `<插件目录>\\..\\joc_core.dll` → `PATH`。 + +然后编辑 `mpv.conf`(同一目录): + +```ini +script-opts=joc-output=binaural,joc-hrtf-source=sofa +``` + +也可以显式加载: + +```powershell +mpv --script="C:\\path\\to\\joc_mpv.dll" --script-opts=joc-output=speaker,joc-layout=7.1 movie.mkv +``` + +## 配置项 + +全部写在 mpv 的 `--script-opts` 里,键名统一以 `joc-` 开头(`mpv.conf` 里一行写完, +用逗号分隔)。未知键会被忽略并在 `joc_decoder.log` 里记一条。 + +| 键 | 取值 | 默认 | 说明 | +|---|---|---|---| +| `joc-enabled` | yes / no | yes | 关掉后插件完全不介入 | +| `joc-output` | binaural / speaker | binaural | 输出形式 | +| `joc-layout` | 2.0 3.1 5.1 7.1 5.1.2 5.1.4 7.1.2 7.1.4 9.1.4 9.1.6 | 7.1 | 扬声器布局;仅 `speaker` 使用 | +| `joc-hrtf-source` | sofa / rosella | sofa | 双耳用哪种 HRTF 输入 | +| `joc-hrtf` | 路径 | 空 | 空则用 `<插件目录>\\HRTF\\` 或 `<插件目录>\\..\\HRTF\\` 下的默认文件名 | +| `joc-mode` | near / mid / far | mid | 双耳模式 | +| `joc-gain-db` | 浮点(dB) | 0 | 渲染增益;双耳可能超过满刻度,需要时在这里衰减 | +| `joc-tail` | 秒 | 5.0 | 双耳房间尾音的长度上限(不作为文件时长交付) | +| `joc-int24` | yes / no | no | 交付 24bit 定点而不是 float32 | +| `joc-object-delay` | 采样 | 1473 | OAMD 对象延迟,与既有实现保持一致 | +| `joc-threads` | 整数 | 0 | 内核线程数,0 = 自选 | +| `joc-ffmpeg` | 路径 | ffmpeg | 核心 PCM 解码用的 ffmpeg | +| `joc-core` | 路径 | 空 | `joc_core.dll` 的显式路径 | +| `joc-wasapi` | auto / yes / no | auto | yes 时把 `ao` 设为 `wasapi` | +| `joc-exclusive` | yes / no | no | 设置 `audio-exclusive=yes`(WASAPI 独占) | +| `joc-chunk` | 秒 | 2.0 | 每次写入 mpv 的音频块大小(0.25–10) | +| `joc-mute-until-ready` | yes / no | yes | 渲染轨就绪前先把文件自带音轨静音,片头不会先播一遍普通 bed | +| `joc-hrtf-cache` | auto / memory / disk / none | auto | 编译后的 HRTF(`.jochrtf`)缓存位置;auto = `\\joc-hrtf-cache` | +| `joc-hrtf-cache-dir` | 路径 | 空 | 显式指定缓存目录 | +| `joc-attach` | yes / no | yes | no = 只提供音频端点、不向播放器加轨(抓取/验证用) | +| `joc-verbose` | yes / no | no | 在日志里记录每个 HTTP 请求与跳转 | +| `joc-log` | 路径 | 空 | 日志文件;空则写 `\\joc_decoder.log` | + +扬声器布局与 WASAPI:WASAPI 端点最多 8 个声道,所以 `9.1.4` / `9.1.6` 这类布局在本插件里 +只能用没有声道掩码的普通 WAV 交付,实际设备上通常拿不到正确映射——需要时请用 `7.1.4` 及以下。 + +## 实现 + +```text +mpv ── 视频/字幕照常 + │ + └─ file-loaded ──► 探测(裸流直接走码流;容器先问 ffmpeg 哪条轨是 E-AC-3、是不是 JOC) + │ + ▼ + joc_core.dll(joc_stream.h) + ▲ E-AC-3 同步帧 + ffmpeg 解出的核心 PCM + │ + ┌───────────┴────────────┐ + │ 渲染成 WAV(float32 / int24,带声道掩码) + │ 由进程内的 loopback HTTP 端点提供,支持 Range + └───────────┬────────────┘ + ▼ + mpv: audio-add http://127.0.0.1:/joc.wav select +``` + +mpv 把这条轨道当成一个**可 seek 的普通 WAV 文件**来读:它自己的 demuxer、缓存、A/V 同步、 +WASAPI 输出和跳转都不用改。 + +启动顺序:`start-file` 时就开始探测并创建渲染器(此时 mpv 还在打开文件),同时把文件自带的 +音轨静音;`file-loaded` 时把渲染轨 `audio-add ... select` 进去,然后恢复原来的静音状态。 +探测判定不是 JOC 的输入立刻恢复,不会留下静音(带 E-AC-3 轨但不是 JOC 的容器会经历一次 +约 100 ms 的 ffmpeg 探测,期间是静音;`joc-mute-until-ready=no` 可关掉这一行为)。实测(30 秒 7.1.4 素材):冷启动约 0.6 秒、 +HRTF 编译结果命中磁盘缓存后约 0.37 秒;这段是静音而不是普通 bed,且 mpv 在切轨时会暂停音频时钟, +所以不会跳过内容。插件只在请求的字节位置和渲染位置不一致时让渲染器重新进入码流 +(与组件的 seek 策略相同:目标帧减去 64 帧预滚,再丢掉目标之前的输出)。 + +跳转与从头播放相比有极低的噪声底差(与组件一致,实测 −65 dBFS 以下),位置本身不漂移。 + +## 与「fork mpv」方案的关系 + +同类成熟项目走的是另一条路:`mpv-omniphony` 是 **mpv 的 fork**,加了一个 `--ad=orender` +解码模块(`ad_orender`),把 demuxer 给出的访问单元交给 `liborender` 做空间渲染;真正的 +编解码在可动态加载的 bridge DLL 里(`harletty_dolby_bridge.dll` 等,E-AC-3 JOC 也在其中)。 +这条路拿到的是"原生"轨道:没有额外音轨、没有启动切换、codec 信息正确。 + +本插件刻意不走 fork:它要求 stock mpv(cplugins),代价是启动时 0.3–0.6 秒的准备窗口,以及 +一条外部 PCM 轨(OSD 里显示为 pcm_f32le)。 + +需要"零妥协"时可以照 mpv-omniphony 的结构给 mpv 加一个 `ad_joc` 模块——mpv 的 AD 层拿得到 +AVPacket,所以不需要改 FFmpeg,内核仍是 `joc_core.dll`。这条路线已经有可构建的原型,见 +[`fork/`](fork/README.md):基于 mpv master(2026-10-17)的 patch、新增源码与构建说明,实测 +`--ad=joc` 的双耳与 7.1 输出都与 `joc_cli` 逐字节一致。代价是要自己维护一个 mpv 构建 +(Windows 上需要 MSYS2/MinGW 工具链)。 + +## 一致性验证 + +`tools/verify_parity.ps1` 用 `joc_cli` 生成参考 WAV,再从插件取回实际交付的字节逐字节比较。 +本机(mpv v0.41.0,FFmpeg 8.0,30 秒 7.1.4 JOC 素材)的结果: + +| 组合 | 结果 | +|---|---| +| 双耳 float32(SOFA) | 1,440,768 采样逐字节一致 | +| 双耳 int24(Rosella) | 1,440,768 采样逐字节一致 | +| 扬声器 7.1 float32 | 1,440,768 采样逐字节一致 | + +参考输出比交付多出的部分是双耳房间尾音:组件和本插件都按文件时长截断,`joc_cli` 的 +`--binaural-output` 不截断。 + +## 构建 + +需要一个 JustOneCacophonyCXX 检出(用它的 `joc_core` 目标): + +```powershell +pwsh -File tools/build.ps1 -JocCoreSource C:\\path\\to\\JustOneCacophonyCXX +``` + +产物在 `build\\Release\\joc_mpv.dll`,`joc_core.dll` 会被复制到同一目录。只想要插件、不重建内核时: + +```powershell +cmake -S . -B build -G "Visual Studio 17 2022" -A x64 +cmake --build build --config Release +``` + +编译选项固定为 `/fp:precise`、静态 CRT:浮点行为是逐字节验收的一部分。 + +## 排错 + +`joc_decoder.log` 写在 mpv 的配置目录(`mpv.conf` 所在目录)里,记录插件版本、核心版本、 +探测结论、每次跳转与 HTTP 请求;ffmpeg 的诊断在同目录的 `joc_ffmpeg_*.log`。 +不能写在 `scripts\\` 里——mpv 会把该目录下的每个文件都当脚本加载。`--msg-level=all=info` +会在终端看到 `JOC: ...` 状态行。 + +常见问题: + +* **没有任何 JOC 提示、听起来是普通 E-AC-3** —— 文件没有 JOC 元数据,或者容器的音频轨不是 + E-AC-3;插件不接管时 mpv 会照常播放原始轨。 +* **双耳报错"找不到 HRTF 文件"** —— 把 `binaural.sofa` 放到 `\\HRTF\\`,或用 + `joc-hrtf` 指定路径。 +* **想确认用的是哪条轨道** —— `joc-verbose=yes` 后看日志里的 `probe:` 与 `start:` 行。 + +## 许可 + +MIT,见 `LICENSE`。渲染内核与解码引擎来自 JustOneCacophonyCXX, +第三方说明见 `THIRD_PARTY_NOTICES.md`。 diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..d67a681 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,45 @@ +# Third-party notices / 第三方通知 + +本仓库是 mpv 与 JustOneCacophony 渲染内核之间的一层前端。它自己不含 DSP 实现,也不分发 +HRTF 数据;下面列出随仓库分发的代码与头文件的来源。 + +## 渲染内核(运行期依赖) + +本仓库自身为 MIT(`LICENSE`);`fork/` 编译进 mpv 后,最终二进制随 mpv 的许可(`LICENSE-mpv`)。 + +`joc_core.dll` 由 [JustOneCacophonyCXX](https://github.com/TheM14/JustOneCacophony) 的 `joc_core` 目标构建 +(MIT,Copyright (c) 2026 TheM14)。本仓库不分发该二进制,`tools/build.ps1` 从给定的 +检出构建并放到插件旁边,`tools/install.ps1` 复制它。JOC 码流解析、双耳/扬声器渲染、 +HRTF 编译与 SIMD 派发全部在它里面,插件只调用 `joc_stream.h` 的 push/pull 接口。 + +## 解码引擎(源码副本) + +`src/joc_decode.{h,cpp}`、`src/container_scan.{h,cpp}`、`src/eac3_scan.{h,cpp}`、 +`src/log.{h,cpp}`、`src/win_path.h` 取自上游项目的前端代码(JustOneCacophony,MIT, +Copyright (c) 2026 TheM14)。它们是渲染与解析部分:码流遍历、容器探测、 +ffmpeg 取核心 PCM、跳转与双耳尾音截断。为在 mpv 里复用,只改了两处: + +* `joc_decode.cpp` 的 `load_api()` 从"链接进同一个二进制"改为按路径 + `LoadLibraryExW` 加载 `joc_core.dll` 并解析 `joc_stream_*` 导出; +* `joc_decode.h` 的 `Settings` 增加 `core_path`(内核 DLL 的显式路径); +* `stderr_path_for()` 在设置了 `JOC_LOG` 时把 ffmpeg 诊断放到日志同目录(插件把它指向 + mpv 的配置目录,避免往 `scripts\\` 里写文件)。 + +## 公共头文件 + +`third_party/joc/include/{joc_core.h,joc_stream.h,joc_version.h}` 是 +JustOneCacophonyCXX 公开 C ABI 的逐字节副本(MIT),供插件与内核按同一 ABI 编译。 +`tools/verify_kernel.ps1` 用 SHA-256 校验它们与源检出一致。 + +`third_party/mpv/client.h` 是 mpv 的 client API 头(ISC,Copyright (c) 2017 the mpv +developers),定义 `MPV_CPLUGIN_DYNAMIC_SYM` 的动态符号表;没有它插件无法在 Windows 上 +找到宿主导出的 `mpv_*` 符号。 + +## HRTF 数据 + +SOFA 测量集与 Rosella `.personalized_headphone` 模型由使用插件的人自行提供,不在本仓库中, +且已写入 `.gitignore`。数据集的许可与再分发条件跟数据一起走,本仓库不做转授。 + +## 专利说明 + +标准可公开获取不等于获准实施相关专利。 diff --git a/config/cplugin-mpv.conf.example b/config/cplugin-mpv.conf.example new file mode 100644 index 0000000..2cbc588 --- /dev/null +++ b/config/cplugin-mpv.conf.example @@ -0,0 +1,25 @@ +# mpv-joc 配置示例:整段放进 mpv.conf 即可。 +# +# 所有键都在 mpv 自己的 --script-opts 命名空间里,前缀 joc-。 +# 只有一行也可以: +# script-opts=joc-output=binaural,joc-hrtf-source=sofa +# +script-opts=joc-output=binaural,joc-hrtf-source=sofa,joc-mode=mid,joc-gain-db=0 + +# 想让插件强制走 WASAPI(默认 auto:不动 mpv 的 ao 选择): +# script-opts-append=joc-wasapi=yes +# WASAPI 独占模式: +# script-opts-append=joc-exclusive=yes +# +# 扬声器布局示例(替换上面的 joc-output / joc-layout): +# script-opts-append=joc-output=speaker +# script-opts-append=joc-layout=7.1 +# +# 指定 HRTF 文件(默认找 \HRTF\binaural.sofa): +# script-opts-append=joc-hrtf=D:/hrtf/MyMeasurements.sofa +# +# 交付 24bit 定点: +# script-opts-append=joc-int24=yes +# +# 排错:把每个 HTTP 请求与跳转写进 joc_decoder.log +# script-opts-append=joc-verbose=yes diff --git a/fork/README.md b/fork/README.md new file mode 100644 index 0000000..e344a32 --- /dev/null +++ b/fork/README.md @@ -0,0 +1,230 @@ +# mpv + ad_joc — 原生轨道的 E-AC-3 JOC 解码器(实验) + +这是 [TheM14/JustOneCacophony](https://github.com/TheM14/JustOneCacophony) 渲染内核在 mpv 里的解码器接入(补丁形式)。内核本身 +不在这里,构建时链接上游的 `joc_core`;行为基准是上游项目自带的 `joc_cli`。 + +这是"接管文件"那条路的最小可行实现:给 **mpv 本身**加一个音频解码模块 `ad_joc`,用 +`--ad=joc` 启用。mpv 的 AD 层拿到的是 demuxer 给的 **AVPacket**(原始 E-AC-3 访问单元), +所以不需要改 FFmpeg;解码出来的对象音频直接作为 mpv 自己的音频流,走它原本的滤镜链、 +重采样、A/V 同步与音频输出。 + +这和插件方案(`mpv-joc` 的 cplugin + loopback 音频源)是两条路: + +| | cplugin + 回环音频源 | `ad_joc`(本目录) | +|---|---|---| +| 改动对象 | 零,stock mpv | mpv 源码,需要自己构建 | +| 轨道 | 额外一条 `pcm_f32le` 外部轨 | 文件自己的轨,codec 显示正确 | +| 片头 | 0.3–0.6 s 准备(静音) | 无 | +| 跳转 | 渲染器可按 64 帧预滚重入 | mpv 不给预滚包,冷启动约 1 s 收敛 | +| 维护 | 跟随 mpv 的 cplugin ABI | 跟随 mpv 的 AD 接口 | + +## 基于哪个 mpv + +mpv master,提交 `01e2533f3143b8940857ca419b0b367f583e05ca`(2026-10-17,`v0.41.0-UNKNOWN`)。 +本目录的 `patches/mpv-ad-joc.patch` 是针对这个提交的 diff,也在 `fffe7a23a8`(2026-10-18) +上无冲突应用并完成构建验证;再新的版本如果碰到上下文变化,需要重新对齐 +`filters/f_decoder_wrapper.c` 里的注册位置。 + +## 组成 + +```text +files/audio/decode/ + ad_joc.c / ad_joc.h 解码器:libavcodec 解 bed + joc_stream 渲染 + 输出 aframe + joc_eac3.c / joc_eac3.h E-AC-3 同步帧/音频帧边界(上游 eac3_scan 的 C 子集) + joc_core.h joc_core 公共头(与 JustOneCacophonyCXX 逐字节一致) + joc_stream.h + joc_version.h +patches/mpv-ad-joc.patch 对 meson.build / meson.options / f_decoder_wrapper / options 的改动 +``` + +注册方式与 mpv-omniphony 的 `ad_orender` 相同:`f_decoder_wrapper.c` 里当 `--ad` 列表包含 +`joc` 且编码是 `eac3` 时切换 driver;`meson.build` 里加源码、链接 `joc_core`、定义 +`HAVE_JOC`;`options/*` 加 `--ad-joc-*` 选项组。 + +## 维护方式:文件 + 锚点,而不是行号补丁 + +仓库里保存的是**新增文件**加**对上游的少量改动**,不是一整份 mpv: + +```text +files/audio/decode/ 7 个新文件(ad_joc / joc_eac3 / 三个 joc 头) +tools/apply_edits.py 把 6 处改动按"锚点"写进 mpv 源码树 +patches/ 同一改动的 diff,供精确复现 +tools/build_fork.ps1 一键:clone 指定 ref → 应用 → 构建 → 打包 +``` + +`apply_edits.py` 不依赖行号:它找 `static bool reinit_decoder`、`if (!driver)`、 +`{"ad-lavc", OPT_SUBSTRUCT(...)}` 这类锚点插入代码,并且是幂等的。上游挪了行、改了上下文都不会 +影响;只有当锚点本身消失(上游重构了这段)时,它会**在改动任何文件之前**报出文件名退出——那就是 +需要人工适配的地方,通常只是换一个新锚点。 + +适配新 mpv 的流程: + +```powershell +.\tools\build_fork.ps1 # clone 最新 master、应用、构建 +.\tools\build_fork.ps1 -MpvRef v0.42.0 +.\tools\build_fork.ps1 -SkipBuild # 只验证能否应用 +``` + +### 自动化(GitHub Actions) + +- 仓库根目录的 `.github/workflows/build.yml`:`workflow_dispatch`(可填 mpv 的 branch/tag/commit)或推 `v*` 标签时, + 在 windows-latest 上 clone 最新 mpv、应用改动、用 MSVC 构建 joc_core、用 MSYS2 构建 mpv、 + 收集 DLL 并上传 `mpv-ad-joc-windows` 产物。 +- 仓库根目录的 `.github/workflows/drift.yml`:每天定时 clone 最新 mpv master,只跑 `apply_edits.py`。锚点失效会直接 + 让这个 job 变红,比发布时才发现要好。 + +> 这两个 workflow 是在本机准备、按本地验证过的步骤写的;GitHub 上还没实际跑过,第一次运行可能 +> 要调依赖路径(尤其 joc_core 的 CMake 产物目录)。 + +## 跨平台 + +代码本身是可移植的:`ad_joc.c` 只有取 exe 目录那段在 `_WIN32` 下(其它平台走 mpv 配置目录搜索), +`joc_core` 的 CMake 里本来就有 `if(UNIX)` 分支(ELF/Mach-O 的 rpath),导出宏也区分了 `_WIN32`。 + +目前只在 Windows 上验证过。移植到 Linux/macOS 需要: + +1. `joc_core` 用系统的 CMake 构建成 `libjoc_core.so`/`.dylib`; +2. meson 找到它,并给它加 rpath(或运行时装 `LD_LIBRARY_PATH`); +3. 构建脚本换成 bash(`build_fork.ps1` 是 Windows 版),CI 加一个 ubuntu/macos job。 + +Android(`libmpv.so`)的可行性调研见 [docs/android.md](docs/android.md)。 + +## 构建(Windows / MSYS2) + +需要 msys2 的 mingw64 环境(本机验证版本:gcc 16.2.0、ffmpeg 9.0.2、meson 1.12.1、ninja 1.13.2): + +```bash +pacman -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-meson \ + mingw-w64-x86_64-ninja mingw-w64-x86_64-pkgconf mingw-w64-x86_64-ffmpeg \ + mingw-w64-x86_64-luajit +``` + +把本目录的 `files/` 覆盖到 mpv 源码树,然后: + +```bash +cd mpv-src +git apply /path/to/patches/mpv-ad-joc.patch +export PATH=/mingw64/bin:$PATH +meson setup build --buildtype=release -Dgpl=false -Dlua=luajit \ + -Djoc-core-dir=/c/path/to/joc_core_import_lib_dir +ninja -C build +``` + +`-Dlua=luajit` 是必须的:mpv 的内置 OSC(进度条 / 播放控制)和所有脚本都编译在 Lua 之上, +不带 Lua 时 `--osc` 选项本身都不存在,界面就是空的。 + +`-Djoc-core-dir` 指向含 `joc_core.lib` 的目录(JustOneCacophonyCXX 的 `joc_core` 构建产物; +本机是 `mpv-joc/build/joc_core/Release`)。运行前把 `joc_core.dll` 放到 `mpv.exe` 旁边。 + +## 用法 + +所有设置都是普通 mpv 选项,写进 `mpv.conf` 就对每次播放生效: + +```ini +# mpv.conf +ad = joc +ad-joc-binaural = yes # 默认就是 yes(双声道输出) +ad-joc-hrtf = C:/HRTF/binaural.sofa # 可省:会自动找 +ad-joc-layout = 7.1 # 仅 binaural=no 时使用 +ad-joc-mode = mid +ad-joc-gain-db = 0 +``` + +命令行等价:`mpv --ad=joc movie.mkv`。 + +| 选项 | 取值 | 默认 | +|---|---|---| +| `--ad-joc-binaural` | yes / no | yes | +| `--ad-joc-hrtf` | SOFA / Rosella / `.jochrtf` 路径 | 空(自动搜索) | +| `--ad-joc-layout` | `2.0` `3.0` `3.1` `4.0` `5.0` `5.1` `5.1.2` `5.1.4` `6.1` `7.0` `7.1` `7.1.2` `7.1.4` `9.1.4` `9.1.6` | 7.1 | +| `--ad-joc-mode` | near / far / mid | mid | +| `--ad-joc-gain-db` | -60 … 12 | 0 | +| `--ad-joc-int24` | yes / no | no | + +`--ad-joc-int24` 把输出量化到渲染器的 24-bit 规则(与上游前端的 int24 交付一致): +clip 到 [-1,1]、乘 8388607、向零截断、取低 24 位,再按 `n / 2^23` 读回。默认关闭, +输出就是渲染器的 float32。 + +本仓库**不附带任何 HRTF 文件**:SOFA、Rosella 模型、编译出的 `.jochrtf` 缓存都不随仓库或发布包 +分发,需要自备。 + +### HRTF 的三种输入与自动判断 + +`--ad-joc-hrtf` 不需要说明类型,按文件内容判断(扩展名只作兜底): + +| 输入 | 判断依据 | 交给渲染器 | +|---|---|---| +| SOFA | HDF5 魔数 `89 48 44 46 0D 0A 1A 0A` | `hrtf_sofa_path` | +| Rosella 个性化模型 | 首字符 `{` 且含 `"personalized_hrtf"` | `personalized_headphone_path` | +| 已编译核 | 扩展名 `.jochrtf` | `hrtf_path` | + +SOFA 编译结果会缓存成 `.jochrtf`(本机首帧 320 ms 左右,命中缓存后 110 ms 左右), +缓存目录是 `/cache/joc-hrtf-cache`,没有 config 目录时用 `/joc-hrtf-cache`。 + +### 不写 `--ad-joc-hrtf` 时 + +按下面的顺序找,找到即用: + +1. `/HRTF/binaural.sofa` +2. `/HRTF/binaural.personalized_headphone` +3. `/HRTF/binaural.jochrtf` +4. `/joc-hrtf/binaural.sofa` +5. `/joc-hrtf/binaural.personalized_headphone` + +都找不到就打印一行提示,退回扬声器布局渲染(默认 7.1),由 mpv 按输出设备下混——双声道 +设备上仍然是双声道输出,不会没声音。 + +普通 E-AC-3(没有 JOC 元数据)不会失败:解码器先看前 8 个音频帧,渲染器一帧都没输出就判定 +这不是 JOC 流,打印一行 `this E-AC-3 stream carries no JOC metadata; decoding it with the +default decoder instead`,然后把已经读掉的包补喂给 mpv 自己的 E-AC-3 解码器,后续照常播放 +(`--ad=joc` 因此可以一直开着,混合片库也能用)。 + +### 便携化(不装 MSYS2 也能双击运行) + +MinGW 构建的 `mpv.exe` 依赖 `/mingw64/bin` 下的一批 DLL。把依赖闭包复制到 `mpv.exe` 旁边即可: + +```bash +bash tools/bundle_dlls.sh /c/path/to/mpv-src/build # 递归 ldd,把 /mingw64 下的依赖拷到 exe 旁边 +``` + +之后 `mpv.exe` 只靠系统目录就能启动(本机实测:`PATH=C:\Windows\System32` 下 `--version` 与播放均正常)。 +`tools/bundle_dlls.sh` 是本目录里的脚本,路径按构建目录改一下即可。 + +## 验证结果(本机) + +用 `--ao=pcm --ao-pcm-file=out.wav` 抓解码器实际输出的 PCM,与 `joc_cli` 的参考 WAV 逐字节比较: + +| 模式 | 结果 | +|---|---| +| 双耳 float32(SOFA,自动发现) | 8 s(3,071,992 B)**逐字节一致** | +| 双耳 float32(Rosella,自动识别) | 8 s(3,071,992 B)**逐字节一致** | +| 扬声器 7.1 float32 | 8 s(12,287,968 B)**逐字节一致** | +| 扬声器 7.1.4 float32 | 8 s **逐字节一致** | +| 扬声器 9.1.4 / 9.1.6 float32 | 能播、通道数正确(14 / 16);通道内容与 `joc_cli` 相同,但 mpv 按自己的标准声道顺序排列,所以字节序列不是逐字节相同 | +| 双耳 int24 | 与 24-bit 规则逐样本一致(256,000 样本 0 差异) | +| 非 JOC 的普通 5.1 E-AC-3 | 打印回退提示,按原生 5.1 播放(exit 0) | +| 默认 `--ad=lavc` | 不受影响,仍是原生 8ch downmix 行为 | + +## 已知限制 + +* **跳转时渲染器会重建**,不复用旧状态:重建前渲染器里排队的输出属于旧位置,若沿用会在 seek 后 + 被当成新位置播放(实测约 1 s,与新旧内容都对不上,RMS ~0.25)。重建后输出就是目标位置的内容, + 与“从该位置新建”的渲染在 1 s 窗口内 RMS ~0.005。 +* 由于 mpv seek 后只给 1 个(有时 0 个)预滚包,重建后的前 ~1 s 与“从头连续渲染”仍有残差 + (末段 ~7e-5):这是缺少历史状态所致,内容本身正确。带文件访问的前端能消除它,是因为 + 它们可以预滚 64 帧,AD 拿不到这些帧。 +* 只注册 `eac3`(`ac3` 没有 JOC)。非 JOC 的 E-AC-3 会自动回退,代价是开头约 0.26 s + (8 帧)的判定窗口。 +* 双耳需要 HRTF:给 `--ad-joc-hrtf`,或把 `binaural.sofa` 放在 `mpv.exe` 旁边;都没有时 + 退回扬声器布局,不再报错退出。 +* 每换一个 mpv 版本都要重新对齐 patch(AD 接口和注册点在 mpv 内部,不在稳定 ABI 里)。 + +## 许可 + +`ad_joc.c` / `ad_joc.h` / `joc_eac3.*` 都是 MIT(见仓库根的 [LICENSE](../LICENSE)): +`joc_eac3.*` 改写自上游的 `eac3_scan.cpp`,`ad_joc.*` 是新增代码。 +它们编译进 mpv,因此最终播放器的分发随 mpv 的许可(LGPL-2.1-or-later,`-Dgpl=true` +时为 GPL-2.0-or-later),全文见 [LICENSE-mpv](../LICENSE-mpv)。 + +`joc_core.h` / `joc_stream.h` / `joc_version.h` 来自 JustOneCacophonyCXX(MIT),逐字节复制。 +`joc_core.dll` 本身仍是 MIT,不在本仓库分发。 diff --git a/fork/docs/android.md b/fork/docs/android.md new file mode 100644 index 0000000..08a1a22 --- /dev/null +++ b/fork/docs/android.md @@ -0,0 +1,64 @@ +# Android:把 ad_joc 编进 libmpv.so 的可行性调研 + +结论:**可行**,arm64-v8a 是主路径。没有架构性障碍;工作量集中在把 `joc_core` 用 NDK 编出来、 +和把它随 APK 一起分发。 + +## 现成的构建体系 + +`mpv-android/mpv-android` 的 `buildscripts/` 就是为这件事准备的: + +- NDK(clang)交叉编译 ffmpeg、libass、libplacebo、luajit、mpv,目标 `android`,API 23; +- mpv 用 meson + 生成的 crossfile: + + ```sh + meson setup build --cross-file "$prefix/crossfile.txt" --default-library shared \ + -Dlibmpv=true -Dcplayer=false -D{lua,libcurl}=enabled + ninja -C build && DESTDIR="$prefix" ninja -C build install + ``` + +- 产物是 `prefix//lib/libmpv.so`,架构可选 `armv7l / arm64 / x86 / x86_64`; +- 脚本只支持 Linux/macOS,GitHub Actions 的 ubuntu runner 正好合适。整个 ffmpeg+mpv 构建 + 约 30–60 分钟,可以缓存。 + +## 我们的补丁落在哪里 + +和 Windows 一样,只是多一个共享库: + +1. 在 mpv 源码树里跑 `tools/apply_edits.py`(纯 Python,与平台无关); +2. 用 NDK 的 CMake toolchain 编 `joc_core` → `libjoc_core.so`; +3. meson 加 `-Djoc-core-dir=/lib`; +4. 运行时 `libjoc_core.so` 必须和 `libmpv.so` 一起进 APK 的 `jniLibs//`, + 这样 `libmpv.so` 的 `DT_NEEDED` 才能解析。 + +## joc_core 的可移植性(源码层面) + +- CMake 已有 `aarch64` 分支和 `src/simd/kernels_intrin_neon.cpp`,`cpu_probe` 用 + `getauxval(AT_HWCAP)` 探测;`JOC_SIMD=auto|scalar|neon` 可强制。 +- 平台相关代码都有 POSIX 分支(`fs_utf8.cpp`、`io/process.cpp` 里的 `#if defined(_WIN32) ... #else`)。 +- 依赖只有 `Threads::Threads`,没有 HDF5 之类的外部库。 +- 导出宏 `JOC_API` 在非 Windows 走 visibility,和 Android 默认的 `-fvisibility=hidden` 兼容。 + +## 需要处理的点 + +| 点 | 说明 | +|---|---| +| armv7l | `JOC_ARCH` 只认 x86_64/x86_32/aarch64,armv7 会退回标量内核:能播,慢。首选 arm64 | +| `std::filesystem` | NDK 的 libc++ 在 API 23 支持;core 里用到的地方(SOFA 缓存、task、io)需要实际编一遍确认 | +| HRTF 路径 | Android 上 `exe_dir()` 为空,必须由 app 传 `--ad-joc-hrtf=/data/user/0//files/binaural.sofa` | +| 缓存目录 | `mp_find_user_file(global, "cache", ...)` 在 Android 上可能拿不到 → 代码已自动退回内存缓存 | +| 许可 | LGPL:动态链接 libmpv.so + libjoc_core.so 合规;发布需附对应源码/补丁 | +| 未验证 | NDK 编 joc_core 的真实报错、NEON 内核在手机上的数值正确性、实时性能 | + +## 建议的落地顺序 + +1. CI 先只做 **arm64 的 joc_core 交叉编译**,产出 `libjoc_core.so`。这一步最快暴露平台问题。 +2. 再跑 mpv-android 的 buildscripts + 我们的 patch,产出 arm64 的 `libmpv.so`。 +3. 在 mpv-android 里加一个最小 demo:`jniLibs/arm64-v8a/libjoc_core.so`,启动参数加 + `--ad=joc --ad-joc-hrtf=...`,用 `adb logcat -s mpv` 验证开始渲染。 +4. 对拍:手机上把输出写成 WAV(`--ao=pcm`),拉回 PC 与 `joc_cli` 比较,确认 NEON 路径正确。 + +## 参考 + +- mpv-android 构建脚本:https://github.com/mpv-android/mpv-android/tree/master/buildscripts +- 交叉编译用的 crossfile 由 `buildall.sh` 生成(`system = 'android'`,`cpu_family` 按架构) +- 现成 libmpv Android 发行版可作对照:https://github.com/jarnedemeulemeester/libmpv-android diff --git a/fork/files/audio/decode/ad_joc.c b/fork/files/audio/decode/ad_joc.c new file mode 100644 index 0000000..a0dd6d5 --- /dev/null +++ b/fork/files/audio/decode/ad_joc.c @@ -0,0 +1,875 @@ +/* + * MIT License, Copyright (c) 2026 TheM14 + * + * This file is compiled into mpv, so the resulting player is distributed under + * mpv's own license (LGPL-2.1-or-later, or GPL-2.0-or-later when built with + * -Dgpl=true). mpv's license text is in LICENSE-mpv. + */ + +/* + * ad_joc.c — mpv audio decoder for E-AC-3 JOC, rendered by the + * JustOneCacophony core (joc_core.dll). + * + * Opt in with --ad=joc. The demuxer hands us E-AC-3 access units; we decode + * the bed with libavcodec (drc off, as the reference frontends do), and push + * each whole audio frame plus its bed PCM into joc_stream. What comes back is + * the object-audio rendering (binaural or a speaker layout) as ordinary float + * PCM, so mpv's resampler, filters, A/V sync and audio output apply unchanged. + * + * This is the "native track" integration: no second audio track, no loopback + * endpoint, correct codec information in the track list. + */ + +#include +#include +#include +#include + +#ifdef _WIN32 +#include +#endif + +#include +#include + +#include "config.h" + +#include "mpv_talloc.h" +#include "osdep/timer.h" + +#include "audio/aframe.h" +#include "audio/chmap.h" +#include "audio/format.h" +#include "common/msg.h" +#include "demux/packet.h" +#include "demux/stheader.h" +#include "filters/f_decoder_wrapper.h" +#include "filters/filter_internal.h" +#include "options/m_config.h" +#include "options/options.h" +#include "options/path.h" +#include "osdep/io.h" + +#include "common/codecs.h" +#include "common/common.h" + +#include "audio/decode/ad_joc.h" +#include "audio/decode/joc_eac3.h" +#include "audio/decode/joc_stream.h" + +#define OPT_BASE_STRUCT struct ad_joc_params + +const struct m_sub_options ad_joc_conf = { + .opts = (const m_option_t[]) { + {"binaural", OPT_BOOL(binaural)}, + {"hrtf", OPT_STRING(hrtf), .flags = M_OPT_FILE}, + {"layout", OPT_STRING(layout), .flags = M_OPT_FILE}, + {"mode", OPT_CHOICE(binaural_mode, + {"near", 1}, {"far", 2}, {"mid", 3})}, + {"gain-db", OPT_DOUBLE(gain_db), M_RANGE(-60.0, 12.0)}, + {"int24", OPT_BOOL(int24)}, + {0} + }, + .size = sizeof(struct ad_joc_params), + .defaults = &(const struct ad_joc_params){ + .binaural = true, + .int24 = false, + .hrtf = "", + .layout = "7.1", + .binaural_mode = 3, + .gain_db = 0.0, + }, +}; + +#define JOC_FRAME_SAMPLES 1536 +#define PULL_BLOCK 4096 + +struct priv { + struct mp_decoder public; + AVCodecContext *avctx; + AVFrame *avframe; + AVPacket *avpkt; + joc_stream *stream; + joc_stream_config cfg; + int out_channels; + struct mp_aframe *fmt; + struct mp_aframe_pool *pool; + uint8_t *carry; + int carry_len; + int carry_cap; + float *bed; + size_t bed_cap; /* floats */ + int bed_channels; + uint64_t frames_in; /* audio frames pushed to the renderer */ + uint64_t samples_out; /* samples handed to mpv */ + uint64_t last_report; /* heartbeat bookkeeping */ + double last_stall_log; /* rate limits the "no output" warning */ + double next_pts; + bool have_pts; + bool eof; + bool binaural; + bool int24; + enum { PATH_UNDECIDED, PATH_JOC, PATH_NATIVE } path; + struct mp_decoder *native; + struct mp_codec_params *codec; + struct mp_frame *probe_packets; + int num_probe_packets; + int probe_packet_pos; + struct mp_frame eof_frame; + bool eof_pending; +}; + +static int append(struct priv *p, const uint8_t *data, int len) +{ + if (len <= 0) + return 0; + if (p->carry_len + len > p->carry_cap) { + int cap = p->carry_cap ? p->carry_cap : 65536; + while (cap < p->carry_len + len) + cap *= 2; + p->carry = talloc_realloc(p, p->carry, uint8_t, cap); + p->carry_cap = cap; + } + memcpy(p->carry + p->carry_len, data, len); + p->carry_len += len; + return len; +} + +static void push_bed(struct priv *p, const uint8_t *data, int bytes) +{ + av_packet_unref(p->avpkt); + if (av_new_packet(p->avpkt, bytes) < 0) + return; + memcpy(p->avpkt->data, data, bytes); + + if (avcodec_send_packet(p->avctx, p->avpkt) < 0) + return; + while (avcodec_receive_frame(p->avctx, p->avframe) == 0) { + int channels = p->avframe->ch_layout.nb_channels; + int samples = p->avframe->nb_samples; + if (channels <= 0 || samples <= 0) { + av_frame_unref(p->avframe); + continue; + } + if (p->bed_channels && p->bed_channels != channels) { + /* The core pairs one audio frame with one bed frame of the channel + * count it derived; a mid-stream change cannot be paired. */ + av_frame_unref(p->avframe); + continue; + } + if (!p->bed_channels) { + p->bed_channels = channels; + MP_VERBOSE(p->public.f, "bed: %d channel(s), %d samples/frame\n", + channels, samples); + } + size_t need = (size_t)samples * channels; + if (need > p->bed_cap) { + p->bed = talloc_realloc(p, p->bed, float, need); + p->bed_cap = need; + } + for (int s = 0; s < samples; ++s) { + for (int c = 0; c < channels; ++c) { + const float *plane = (const float *)p->avframe->extended_data[c]; + p->bed[(size_t)s * channels + c] = plane[s]; + } + } + joc_stream_buffer in; + memset(&in, 0, sizeof(in)); + in.struct_size = sizeof(in); + in.struct_version = 1; + in.kind = JOC_STREAM_IN_CORE_PCM; + in.channels = (uint32_t)channels; + in.sample_rate = 48000; + in.sample_count = (uint32_t)samples; + in.pcm = p->bed; + joc_stream_push(p->stream, &in, NULL, NULL); + av_frame_unref(p->avframe); + } +} + +static void feed(struct priv *p, int end_of_stream) +{ + if (!p->stream) + return; + for (;;) { + size_t bytes = joc_eac3_audio_frame_bytes(p->carry, (size_t)p->carry_len, 0, + end_of_stream); + if (bytes == 0 || (int)bytes > p->carry_len) + break; + joc_stream_buffer in; + memset(&in, 0, sizeof(in)); + in.struct_size = sizeof(in); + in.struct_version = 1; + in.kind = JOC_STREAM_IN_EAC3; + in.bytes = p->carry; + in.byte_count = (uint32_t)bytes; + uint32_t consumed = 0; + if (joc_stream_push(p->stream, &in, NULL, &consumed) != JOC_OK) { + MP_ERR(p->public.f, "renderer refused an E-AC-3 frame (%u bytes): %s\n", + bytes, joc_last_error_detail()); + break; + } + p->frames_in++; + push_bed(p, p->carry, (int)bytes); + int left = p->carry_len - (int)bytes; + if (left > 0) + memmove(p->carry, p->carry + bytes, (size_t)left); + p->carry_len = left; + } +} + +static float quantize_int24(float v); + +static bool emit(struct mp_filter *f) +{ + struct priv *p = f->priv; + if (!p->stream || !mp_pin_in_needs_data(f->ppins[1])) + return false; + + struct mp_aframe *frame = mp_aframe_new_ref(p->fmt); + if (!frame) + return false; + if (mp_aframe_pool_allocate(p->pool, frame, PULL_BLOCK) < 0) { + talloc_free(frame); + return false; + } + uint8_t **data = mp_aframe_get_data_rw(frame); + if (!data) { + talloc_free(frame); + return false; + } + + joc_stream_buffer out; + memset(&out, 0, sizeof(out)); + out.struct_size = sizeof(out); + out.struct_version = 1; + out.kind = p->binaural ? JOC_STREAM_OUT_BINAURAL : JOC_STREAM_OUT_SPEAKER; + out.channels = (uint32_t)p->out_channels; + out.sample_rate = 48000; + out.sample_count = PULL_BLOCK; + out.out_pcm = (float *)data[0]; + uint32_t produced = 0; + joc_error rc = joc_stream_pull(p->stream, &out, &produced); + if (rc != JOC_OK) { + MP_ERR(f, "renderer pull failed: %s\n", joc_last_error_detail()); + talloc_free(frame); + return false; + } + if (produced == 0) { + const double now = mp_time_sec(); + joc_stream_status_info st = { .struct_size = sizeof(st), .struct_version = 1 }; + joc_stream_status(p->stream, &st); + /* A frame still waiting in carry is normal: the renderer pulls only + * what it has already rendered. Only a dry renderer with nothing in + * flight means the pipeline actually stopped. */ + if (p->carry_len == 0 && st.buffered_samples == 0 && + now - p->last_stall_log > 1.0) { + p->last_stall_log = now; + MP_WARN(f, "no output: frames_in=%llu frames_out=%llu samples_out=%llu " + "buffered=%llu carry=%d eof=%d state=%d\n", + (unsigned long long)st.frames_in, + (unsigned long long)st.frames_out, + (unsigned long long)p->samples_out, + (unsigned long long)st.buffered_samples, + p->carry_len, p->eof, (int)p->path); + } + talloc_free(frame); + return false; + } + + /* The renderer's room tail is not part of the file: stop at the sample the + * last input frame ends on, exactly as the file frontends do. */ + uint64_t total = p->frames_in * JOC_FRAME_SAMPLES; + uint64_t left = (p->samples_out < total) ? total - p->samples_out : 0; + if ((uint64_t)produced > left) + produced = (uint32_t)left; + if (produced == 0) { + talloc_free(frame); + return false; + } + if (p->int24) { + float *s = (float *)data[0]; + for (size_t i = 0; i < (size_t)produced * (size_t)p->out_channels; i++) + s[i] = quantize_int24(s[i]); + } + mp_aframe_set_size(frame, (int)produced); + mp_aframe_set_pts(frame, p->next_pts); + p->next_pts += (double)produced / 48000.0; + p->samples_out += produced; + if (p->frames_in != p->last_report && p->frames_in % 128 == 0) { + p->last_report = p->frames_in; + joc_stream_status_info st = { .struct_size = sizeof(st), .struct_version = 1 }; + joc_stream_status(p->stream, &st); + MP_VERBOSE(f, "frames_in=%llu samples_out=%llu buffered=%llu\n", + (unsigned long long)p->frames_in, + (unsigned long long)p->samples_out, + (unsigned long long)st.buffered_samples); + } + mp_pin_in_write(f->ppins[1], MAKE_FRAME(MP_FRAME_AUDIO, frame)); + return true; +} + +static void clear_probe_packets(struct priv *p) +{ + for (int i = p->probe_packet_pos; i < p->num_probe_packets; i++) + mp_frame_unref(&p->probe_packets[i]); + p->num_probe_packets = 0; + p->probe_packet_pos = 0; +} + +/* The track is not JOC: hand it to mpv's normal E-AC-3 decoder and replay the + * packets that were kept while classifying, so the track still plays (and a + * seek that happened first is transparent). */ +static bool switch_to_native(struct mp_filter *f, struct priv *p) +{ + if (p->native) + return true; + + struct mp_decoder_list *all = talloc_zero(NULL, struct mp_decoder_list); + ad_lavc.add_decoders(all); + struct mp_decoder_list *sel = + mp_select_decoders(f->log, all, p->codec->codec, NULL); + talloc_free(all); + for (int i = 0; i < sel->num_entries && !p->native; i++) + p->native = ad_lavc.create(f, p->codec, sel->entries[i].decoder); + talloc_free(sel); + if (!p->native) { + MP_ERR(f, "no native E-AC-3 decoder to fall back to\n"); + return false; + } + + MP_WARN(f, "this E-AC-3 stream carries no JOC metadata; decoding it with " + "the default decoder instead\n"); + if (p->stream) { + joc_stream_destroy(p->stream); + p->stream = NULL; + } + p->path = PATH_NATIVE; + return true; +} + +/* Host mode: pump the native child — packets in, decoded frames out. */ +static void process_host(struct mp_filter *f, struct priv *p) +{ + if (!switch_to_native(f, p)) { + mp_filter_internal_mark_failed(f); + return; + } + + struct mp_pin *child_in = p->native->f->pins[0]; + struct mp_pin *child_out = p->native->f->pins[1]; + + if (mp_pin_can_transfer_data(f->ppins[1], child_out)) { + struct mp_frame frame = mp_pin_out_read(child_out); + mp_pin_in_write(f->ppins[1], frame); + } + if (p->probe_packet_pos < p->num_probe_packets && + mp_pin_in_needs_data(child_in)) { + struct mp_frame frame = p->probe_packets[p->probe_packet_pos]; + p->probe_packets[p->probe_packet_pos++] = MP_NO_FRAME; + mp_pin_in_write(child_in, frame); + if (p->probe_packet_pos == p->num_probe_packets) { + p->num_probe_packets = 0; + p->probe_packet_pos = 0; + } + } else if (mp_pin_can_transfer_data(child_in, f->ppins[0])) { + struct mp_frame frame = mp_pin_out_read(f->ppins[0]); + mp_pin_in_write(child_in, frame); + } +} + +/* True when the renderer accepted these frames as JOC. A stream without any + * EMDF metadata never produces output and counts every frame as missing. */ +static bool classify_has_joc(struct priv *p) +{ + joc_stream_status_info st; + memset(&st, 0, sizeof(st)); + st.struct_size = sizeof(st); + st.struct_version = 1; + if (joc_stream_status(p->stream, &st) != JOC_OK) + return true; + return st.frames_out > 0; +} + +static void ad_joc_process(struct mp_filter *f) +{ + struct priv *p = f->priv; + + if (p->path == PATH_NATIVE) { + process_host(f, p); + return; + } + if (!mp_pin_in_needs_data(f->ppins[1])) + return; + + /* End of stream: the renderer still holds its tail, and the EOF frame is + * only forwarded once that tail has been handed out. Draining has to + * happen before touching the input pin, which stays empty from here on. */ + if (p->eof_pending) { + if (emit(f)) + return; + struct mp_frame eof = p->eof_frame; + p->eof_pending = false; + p->eof_frame = MP_NO_FRAME; + mp_pin_in_write(f->ppins[1], eof); + return; + } + + struct mp_frame in = mp_pin_out_read(f->ppins[0]); + if (in.type == MP_FRAME_EOF) { + if (p->path == PATH_UNDECIDED && p->frames_in > 0) { + if (classify_has_joc(p)) { + p->path = PATH_JOC; + clear_probe_packets(p); + } else if (switch_to_native(f, p)) { + struct mp_pin *child_in = p->native->f->pins[0]; + for (int i = 0; i < p->num_probe_packets; i++) { + if (!mp_pin_in_needs_data(child_in)) + break; + struct mp_frame pf = p->probe_packets[i]; + p->probe_packets[i] = MP_NO_FRAME; + mp_pin_in_write(child_in, pf); + } + clear_probe_packets(p); + if (mp_pin_in_needs_data(child_in)) + mp_pin_in_write(child_in, in); + else + mp_frame_unref(&in); + process_host(f, p); + mp_filter_internal_mark_progress(f); + return; + } + } + if (!p->eof) { + p->eof = true; + if (p->carry_len > 0) { + feed(p, 1); + p->carry_len = 0; + } + joc_stream_flush(p->stream); + } + p->eof_frame = in; + p->eof_pending = true; + if (emit(f)) + return; + /* Nothing buffered: forward EOF immediately. */ + struct mp_frame eof = p->eof_frame; + p->eof_pending = false; + p->eof_frame = MP_NO_FRAME; + mp_pin_in_write(f->ppins[1], eof); + return; + } + if (in.type != MP_FRAME_PACKET) { + if (in.type) + MP_ERR(f, "unexpected frame type\n"); + return; + } + + struct demux_packet *pkt = in.data; + if (!p->have_pts && pkt->pts != MP_NOPTS_VALUE) { + p->next_pts = pkt->pts; + p->have_pts = true; + } + /* Keep what was read while classifying the track: if it turns out to have + * no JOC payload, these packets are replayed into the native decoder. */ + bool retained = false; + if (p->path == PATH_UNDECIDED && p->num_probe_packets < 16) { + MP_TARRAY_APPEND(p, p->probe_packets, p->num_probe_packets, in); + retained = true; + } + append(p, pkt->buffer, pkt->len); + feed(p, 0); + if (!retained) + talloc_free(pkt); + + if (p->path == PATH_UNDECIDED && p->frames_in >= 8) { + if (classify_has_joc(p)) { + p->path = PATH_JOC; + clear_probe_packets(p); + } else { + process_host(f, p); + return; + } + } + + if (emit(f)) + return; + mp_filter_internal_mark_progress(f); +} + +static void ad_joc_reset(struct mp_filter *f) +{ + struct priv *p = f->priv; + if (p->path == PATH_UNDECIDED) + clear_probe_packets(p); + /* mpv restarts the packet stream at the seek target without pre-roll, so + * the renderer cannot be carried across the discontinuity: whatever it + * buffered belongs to the old position and would be emitted as if it were + * the new one. Restart it instead; the missing history costs a short + * convergence, the stale tail would be audible for about a second. */ + if (p->stream) { + joc_stream_destroy(p->stream); + p->stream = NULL; + if (joc_stream_create(&p->cfg, &p->stream) != JOC_OK) { + MP_ERR(f, "cannot restart the renderer after a seek: %s\n", + joc_last_error_detail()); + p->stream = NULL; + } + } + p->frames_in = 0; + p->samples_out = 0; + if (p->avctx) + avcodec_flush_buffers(p->avctx); + if (p->path == PATH_NATIVE) + return; + p->carry_len = 0; + p->have_pts = false; + p->eof = false; + p->bed_channels = 0; +} + +static void ad_joc_destroy(struct mp_filter *f) +{ + struct priv *p = f->priv; + if (p->stream) { + joc_stream_destroy(p->stream); + p->stream = NULL; + } + if (p->avctx) + avcodec_free_context(&p->avctx); + av_frame_free(&p->avframe); + av_packet_free(&p->avpkt); +} + +static const struct mp_filter_info ad_joc_filter = { + .name = "ad_joc", + .priv_size = sizeof(struct priv), + .process = ad_joc_process, + .reset = ad_joc_reset, + .destroy = ad_joc_destroy, +}; + +/* mpv names layouts up to 7.1 itself; the renderer goes further (it is a Dolby + * Atmos renderer, so 5.1.2 … 9.1.6 follow the usual speaker order). Spell the + * wider ones out as speaker lists so mpv knows which channel is which. */ +static const struct { + const char *name; + const char *speakers; +} layout_names[] = { + {"2.0", "fl-fr"}, + {"3.0", "fl-fr-fc"}, + {"3.1", "fl-fr-fc-lfe"}, + {"4.0", "fl-fr-fc-bc"}, + {"5.0", "fl-fr-fc-bl-br"}, + {"5.1", "fl-fr-fc-lfe-bl-br"}, + {"5.1.2", "fl-fr-fc-lfe-bl-br-tfl-tfr"}, + {"5.1.4", "fl-fr-fc-lfe-bl-br-tfl-tfr-tbl-tbr"}, + {"6.1", "fl-fr-fc-lfe-bc-sl-sr"}, + {"7.0", "fl-fr-fc-bl-br-sl-sr"}, + {"7.1", "fl-fr-fc-lfe-bl-br-sl-sr"}, + {"7.1.2", "fl-fr-fc-lfe-bl-br-sl-sr-tfl-tfr"}, + {"7.1.4", "fl-fr-fc-lfe-bl-br-sl-sr-tfl-tfr-tbl-tbr"}, + {"9.1.4", "fl-fr-fc-lfe-bl-br-sl-sr-wl-wr-tfl-tfr-tbl-tbr"}, + {"9.1.6", "fl-fr-fc-lfe-bl-br-sl-sr-wl-wr-tfl-tfr-tsl-tsr-tbl-tbr"}, +}; + +static bool layout_chmap(struct mp_chmap *chmap, const char *layout, int channels) +{ + for (int i = 0; i < MP_ARRAY_SIZE(layout_names); i++) { + if (strcmp(layout, layout_names[i].name) == 0) { + if (mp_chmap_from_str(chmap, bstr0(layout_names[i].speakers)) && + chmap->num == channels) + return true; + break; + } + } + if (mp_chmap_from_str(chmap, bstr0(layout)) && chmap->num == channels) + return true; + /* Unknown to mpv: keep the channels, just do not name them. */ + mp_chmap_from_channels(chmap, channels); + return chmap->num == channels; +} + +/* The renderer's int24 rule (the core's wav_writer to_int32): + * clip, scale by 8388607, truncate toward zero, keep the low 24 bits, and read + * back the value the host sees: n / 2^23. */ +static float quantize_int24(float v) +{ + if (!isfinite(v)) + return 0.0f; + if (v > 1.0f) + v = 1.0f; + else if (v < -1.0f) + v = -1.0f; + int32_t scaled = (int32_t)(v * 8388607.0f); + int32_t written = scaled & 0xFFFFFF; + if (written & 0x800000) + written -= 0x1000000; + return (float)written / 8388608.0f; +} + +enum hrtf_kind { HRTF_UNKNOWN, HRTF_SOFA, HRTF_ROSELLA, HRTF_KERNELS }; + +static bool file_exists(const char *path) +{ + if (!path || !path[0]) + return false; + FILE *fp = fopen(path, "rb"); + if (!fp) + return false; + fclose(fp); + return true; +} + +static bool ends_with_ci(const char *s, const char *suffix) +{ + size_t a = strlen(s), b = strlen(suffix); + if (a < b) + return false; + for (size_t i = 0; i < b; i++) { + char x = s[a - b + i], y = suffix[i]; + if (x >= 'A' && x <= 'Z') x += 32; + if (y >= 'A' && y <= 'Z') y += 32; + if (x != y) + return false; + } + return true; +} + +static bool contains(const void *hay, size_t n, const char *needle) +{ + size_t m = strlen(needle); + if (n < m) + return false; + for (size_t i = 0; i + m <= n; i++) { + if (memcmp((const unsigned char *)hay + i, needle, m) == 0) + return true; + } + return false; +} + +/* The renderer takes three kinds of HRTF input and the user should not have to + * say which: SOFA is HDF5, the Rosella model is JSON with a personalized_hrtf + * object, and a compiled kernel is a .jochrtf. Look at the extension first + * (conclusive for kernels), then at the file signature. */ +static enum hrtf_kind hrtf_kind_of(const char *path) +{ + if (!path || !path[0]) + return HRTF_UNKNOWN; + if (ends_with_ci(path, ".jochrtf")) + return HRTF_KERNELS; + + unsigned char head[4096]; + FILE *fp = fopen(path, "rb"); + if (!fp) + return HRTF_UNKNOWN; + size_t n = fread(head, 1, sizeof(head), fp); + fclose(fp); + + if (n >= 8 && memcmp(head, "\x89HDF\r\n\x1a\n", 8) == 0) + return HRTF_SOFA; + for (size_t i = 0; i < n; i++) { + if (head[i] == ' ' || head[i] == '\t' || head[i] == '\r' || head[i] == '\n') + continue; + if (head[i] == '{' && contains(head, n, "\"personalized_hrtf\"")) + return HRTF_ROSELLA; + break; + } + if (ends_with_ci(path, ".sofa")) + return HRTF_SOFA; + return HRTF_UNKNOWN; +} + +static char *exe_dir(void *ta) +{ +#ifdef _WIN32 + wchar_t wpath[MP_PATH_MAX]; + DWORD len = GetModuleFileNameW(NULL, wpath, MP_PATH_MAX); + while (len > 0 && wpath[len - 1] != L'\\' && wpath[len - 1] != L'/') + len--; + if (len > 0) + wpath[len - 1] = 0; + return mp_to_utf8(ta, wpath); +#else + return NULL; +#endif +} + +/* Explicit --ad-joc-hrtf wins; otherwise look where the standalone renderer + * looks: HRTF/binaural.sofa or HRTF/binaural.personalized_headphone next to + * mpv.exe, then the same names under the mpv config directory. */ +static char *find_hrtf(struct mp_filter *da, struct ad_joc_params *opts) +{ + struct priv *p = da->priv; + if (opts->hrtf && opts->hrtf[0]) { + char *path = mp_get_user_path(p, da->global, opts->hrtf); + if (file_exists(path)) + return path; + MP_ERR(da, "HRTF file not found: %s\n", path); + return NULL; + } + + static const char *const names[] = { + "HRTF/binaural.sofa", + "HRTF/binaural.personalized_headphone", + "HRTF/binaural.jochrtf", + "joc-hrtf/binaural.sofa", + "joc-hrtf/binaural.personalized_headphone", + }; + char *dir = exe_dir(p); + for (int i = 0; i < MP_ARRAY_SIZE(names); i++) { + char *cand = dir ? mp_path_join(p, dir, names[i]) : NULL; + if (file_exists(cand)) + return cand; + cand = mp_find_config_file(p, da->global, names[i]); + if (file_exists(cand)) + return cand; + } + return NULL; +} + +static struct mp_decoder *create(struct mp_filter *parent, + struct mp_codec_params *codec, + const char *decoder) +{ + if (!codec->codec || strcmp(codec->codec, "eac3") != 0) + return NULL; + + struct mp_filter *da = mp_filter_create(parent, &ad_joc_filter); + if (!da) + return NULL; + mp_filter_add_pin(da, MP_PIN_IN, "in"); + mp_filter_add_pin(da, MP_PIN_OUT, "out"); + da->log = mp_log_new(da, parent->log, NULL); + + (void)decoder; + struct priv *p = da->priv; + struct ad_joc_params *opts = mp_get_config_group(p, da->global, &ad_joc_conf); + bool binaural = opts->binaural; + char *hrtf_path = NULL; + enum hrtf_kind hrtf_kind = HRTF_UNKNOWN; + if (binaural) { + hrtf_path = find_hrtf(da, opts); + hrtf_kind = hrtf_kind_of(hrtf_path); + if (hrtf_kind == HRTF_UNKNOWN) { + MP_WARN(da, "no usable HRTF found%s%s; rendering the speaker layout " + "instead (mpv downmixes it to stereo). Place " + "HRTF/binaural.sofa next to mpv.exe or set --ad-joc-hrtf.\n", + hrtf_path ? ": " : "", hrtf_path ? hrtf_path : ""); + binaural = false; + } + } + + const AVCodec *lavc = avcodec_find_decoder(AV_CODEC_ID_EAC3); + if (!lavc) { + MP_ERR(da, "libavcodec has no E-AC-3 decoder for the bed\n"); + talloc_free(da); + return NULL; + } + p->avctx = avcodec_alloc_context3(lavc); + p->avframe = av_frame_alloc(); + p->avpkt = av_packet_alloc(); + if (!p->avctx || !p->avframe || !p->avpkt) { + talloc_free(da); + return NULL; + } + p->avctx->pkt_timebase = (AVRational){1, 48000}; + /* The reference frontends decode the bed without applying the stream's + * dynamic range metadata. */ + av_opt_set_double(p->avctx->priv_data, "drc_scale", 0.0, 0); + if (avcodec_open2(p->avctx, lavc, NULL) < 0) { + MP_ERR(da, "cannot open the E-AC-3 bed decoder\n"); + talloc_free(da); + return NULL; + } + + joc_stream_config cfg; + memset(&cfg, 0, sizeof(cfg)); + cfg.struct_size = sizeof(cfg); + cfg.struct_version = 1; + cfg.input = JOC_STREAM_IN_EAC3; + cfg.output = binaural ? JOC_STREAM_OUT_BINAURAL : JOC_STREAM_OUT_SPEAKER; + cfg.binaural_mode = (uint32_t)opts->binaural_mode; + cfg.gain_db = opts->gain_db; + cfg.object_delay_samples = 1473; + if (binaural) { + if (hrtf_kind == HRTF_SOFA) + cfg.hrtf_sofa_path = hrtf_path; + else if (hrtf_kind == HRTF_ROSELLA) + cfg.personalized_headphone_path = hrtf_path; + else if (hrtf_kind == HRTF_KERNELS) + cfg.hrtf_path = hrtf_path; + /* Compiling a SOFA is expensive; keep the kernels between runs. */ + char *cache = mp_find_user_file(p, da->global, "cache", "joc-hrtf-cache"); + if (!cache) { + char *dir = exe_dir(p); + if (dir) + cache = mp_path_join(p, dir, "joc-hrtf-cache"); + } + if (cache) { + mp_mkdirp(cache); + cfg.hrtf_cache_dir = cache; + cfg.hrtf_cache_policy = 2; + } else { + cfg.hrtf_cache_policy = 1; + } + } else { + cfg.speaker_layout_name = opts->layout; + } + p->cfg = cfg; + if (joc_stream_create(&cfg, &p->stream) != JOC_OK) { + MP_ERR(da, "cannot create the renderer stream: %s\n", joc_last_error_detail()); + talloc_free(da); + return NULL; + } + + joc_stream_status_info status; + memset(&status, 0, sizeof(status)); + status.struct_size = sizeof(status); + status.struct_version = 1; + int channels = binaural ? 2 : 0; + if (joc_stream_status(p->stream, &status) == JOC_OK && status.output_channels) + channels = (int)status.output_channels; + if (channels <= 0) + channels = binaural ? 2 : 8; + + struct mp_chmap chmap; + if (binaural) { + mp_chmap_from_channels(&chmap, 2); + } else if (!layout_chmap(&chmap, opts->layout, channels)) { + MP_ERR(da, "unknown speaker layout '%s'\n", opts->layout); + talloc_free(da); + return NULL; + } + p->out_channels = channels; + + p->fmt = mp_aframe_create(); + mp_aframe_set_format(p->fmt, AF_FORMAT_FLOAT); + mp_aframe_set_chmap(p->fmt, &chmap); + mp_aframe_set_rate(p->fmt, 48000); + p->pool = mp_aframe_pool_create(p); + + p->public.f = da; + p->binaural = binaural; + p->codec = codec; + p->path = PATH_UNDECIDED; + p->int24 = opts->int24; + codec->codec_desc = "E-AC-3 JOC (joc_core renderer)"; + MP_VERBOSE(da, "renderer: %s, %d channel(s)%s%s\n", + binaural ? "binaural" : opts->layout, p->out_channels, + binaural ? ", hrtf: " : "", binaural ? hrtf_path : ""); + if (p->int24) + MP_INFO(da, "int24: quantising the output to the renderer's 24-bit rule\n"); + return &p->public; +} + +static void add_decoders(struct mp_decoder_list *list) +{ + mp_add_decoder(list, "eac3", "joc", + "E-AC-3 JOC object renderer (joc_core)"); +} + +const struct mp_decoder_fns ad_joc = { + .create = create, + .add_decoders = add_decoders, +}; diff --git a/fork/files/audio/decode/ad_joc.h b/fork/files/audio/decode/ad_joc.h new file mode 100644 index 0000000..f0582c7 --- /dev/null +++ b/fork/files/audio/decode/ad_joc.h @@ -0,0 +1,27 @@ +/* + * MIT License, Copyright (c) 2026 TheM14 + * + * This file is compiled into mpv, so the resulting player is distributed under + * mpv's own license (LGPL-2.1-or-later, or GPL-2.0-or-later when built with + * -Dgpl=true). mpv's license text is in LICENSE-mpv. + */ + +/* --ad-joc-* options, shared by the decoder (audio/decode/ad_joc.c) and the + * option table (options/options.c). These are ordinary mpv options, so + * mpv.conf carries them: "ad-joc-binaural=yes", "ad-joc-hrtf=...". */ +#pragma once + +#include + +#include "options/m_option.h" + +struct ad_joc_params { + bool binaural; /* binaural (stereo) output; off uses the speaker layout */ + char *hrtf; /* SOFA / Rosella / .jochrtf; the kind is detected */ + char *layout; /* speaker layout name, e.g. "7.1" or "9.1.6" */ + bool int24; /* quantise the output to the renderer's int24 rule */ + int binaural_mode; /* JOC_BINAURAL_NEAR(1) / FAR(2) / MID(3) */ + double gain_db; +}; + +extern const struct m_sub_options ad_joc_conf; diff --git a/fork/files/audio/decode/joc_core.h b/fork/files/audio/decode/joc_core.h new file mode 100644 index 0000000..40d6a96 --- /dev/null +++ b/fork/files/audio/decode/joc_core.h @@ -0,0 +1,492 @@ +/* + * joc_core.h -- JustOneCacophony C++ Core, public ABI. Pure C. + * + * This header is the single authoritative definition of the Core's public + * parameter/error surface. Frontends (thin Python CLI, joc_dump, foobar2000, + * MPV, FFmpeg) only ever fill these POD structs and read these POD results; + * no audio data, no internal DSP concept, and no Python type crosses this + * boundary. + * + * Stability tiers + * --------------- + * [T1] host tier + * joc_abi_version / joc_version_string / joc_build_info, joc_error, + * joc_error_name / joc_error_stage, joc_last_error_detail. + * Stable, versioned, safe for media hosts. + * + * [T2] bitstream / verification tier + * joc_parse_eac3_frame, joc_parse_id14, joc_frame_params, joc_emdf_info. + * These deliberately expose the dequantized JOC matrix coefficients so the + * bitstream front-end can be validated bit-exactly and driven by tooling + * (joc_dump) and A/B harnesses. Media hosts must NOT use this tier; they + * use the task/stream API (added in later milestones). + * + * Conventions + * ----------- + * * every struct's first two fields are struct_size / struct_version; + * * all arrays are fixed size and POD, no pointers, no allocation; + * * every function returns joc_error (JOC_OK == 0); + * * joc_last_error_detail() returns a thread-local message that stays valid + * until the next Core call on the same thread. + */ +#pragma once + +#include +#include + +#include "joc_version.h" + +#define JOC_ABI_VERSION 5u +#define JOC_FRAME_PARAMS_VERSION 1u +#define JOC_EMDF_INFO_VERSION 1u +#define JOC_TASK_CONFIG_VERSION 3u +#define JOC_TASK_RESULT_VERSION 2u +#define JOC_EVENT_VERSION 1u + +/* JOC_STATIC: this branch exists for building the sources directly into an application, where nothing is imported or exported. */ +#if defined(JOC_STATIC) + #define JOC_API + #define JOC_CALL __cdecl +#elif defined(_WIN32) + #if defined(JOC_BUILD_DLL) + #define JOC_API __declspec(dllexport) + #else + #define JOC_API __declspec(dllimport) + #endif + #define JOC_CALL __cdecl +#else + #define JOC_API __attribute__((visibility("default"))) + #define JOC_CALL +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/* ------------------------------------------------------------------ */ +/* Fixed layout constants (single source of truth for every frontend) */ +/* ------------------------------------------------------------------ */ +enum { + JOC_FRAME_SAMPLES = 1536, /* E-AC-3 frame = 24 * 64 */ + JOC_TIMESLOTS = 24, + JOC_SUBBANDS = 64, + JOC_CORE_CHANNELS = 5, /* L R C Ls Rs (JOC order) */ + JOC_MAX_CORE_CHANNELS = 7, /* dmx_config_idx 1/2/4 declare 7 */ + JOC_OUTPUT_CHANNELS = 16, /* ch0 = LFE, ch1..15 = objects */ + JOC_MAX_OBJECTS = 15, + JOC_MAX_DPOINTS = 2, + JOC_MAX_PARAMETER_BANDS = 23, + JOC_MAX_EMDF_PAYLOADS = 16, + JOC_SPEAKER_BLOCK_SAMPLES = 32, + JOC_BINAURAL_BLOCK_SAMPLES = 512, + JOC_BINAURAL_QMF_BANDS = 64, + JOC_BINAURAL_HYBRID_BANDS = 77, + JOC_QMF_HOP_SAMPLES = 64, + JOC_BINAURAL_LATENCY_SAMPLES = 961, + JOC_LFE_DELAY_SAMPLES = 1217 +}; + +/* ------------------------------------------------------------------ */ +/* [T1] library / error surface */ +/* ------------------------------------------------------------------ */ +typedef enum joc_error { + JOC_OK = 0, + JOC_ERR_INVALID_ARGUMENT, + JOC_ERR_INVALID_CONFIG, + JOC_ERR_OUT_OF_MEMORY, + JOC_ERR_IO, + JOC_ERR_UNSUPPORTED_PLATFORM, + JOC_ERR_LIBRARY_MISSING, + /* input / bitstream */ + JOC_ERR_INPUT_NOT_FOUND, + JOC_ERR_INPUT_FORMAT, + JOC_ERR_EAC3_SYNCFRAME, + JOC_ERR_EMDF_TRANSPORT, + JOC_ERR_EMDF_SYNTAX, + JOC_ERR_JOC_SYNTAX, + JOC_ERR_JOC_UNSUPPORTED_VARIANT, + JOC_ERR_OAMD_SYNTAX, + JOC_ERR_OAMD_UNSUPPORTED_VARIANT, + JOC_ERR_BITSTREAM_TRUNCATED, + JOC_ERR_BITSTREAM_PADDING, + /* resources */ + JOC_ERR_HRTF_NOT_FOUND, + JOC_ERR_HRTF_FORMAT, + JOC_ERR_HRTF_VERSION, + JOC_ERR_HRTF_HASH, + JOC_ERR_HRTF_UNSUPPORTED_CONVENTION, + /* rendering / output */ + JOC_ERR_LAYOUT_UNSUPPORTED, + JOC_ERR_RENDER_FAILED, + JOC_ERR_OUTPUT_OPEN, + JOC_ERR_OUTPUT_WRITE, + JOC_ERR_OUTPUT_CLIP_ABORT, + JOC_ERR_ADM_VALIDATION, + /* task / stream */ + JOC_ERR_CANCELLED, + JOC_ERR_STATE, + JOC_ERR_NOT_SUPPORTED, + JOC_ERR_INTERNAL +} joc_error; + +JOC_API uint32_t JOC_CALL joc_abi_version(void); +JOC_API const char* JOC_CALL joc_version_string(void); +JOC_API const char* JOC_CALL joc_build_info(void); +/* Struct sizes, so a binding can assert its layout matches the library instead of + * assuming (mismatches are otherwise silent memory corruption). */ +JOC_API uint32_t JOC_CALL joc_event_size(void); +JOC_API uint32_t JOC_CALL joc_task_config_size(void); +JOC_API uint32_t JOC_CALL joc_task_result_size(void); +JOC_API const char* JOC_CALL joc_error_name(joc_error code); +JOC_API const char* JOC_CALL joc_error_stage(joc_error code); +/* Thread-local structured detail for the most recent failing call. */ +JOC_API const char* JOC_CALL joc_last_error_detail(void); + +/* ------------------------------------------------------------------ */ +/* [T2] bitstream / verification tier */ +/* ------------------------------------------------------------------ */ + +/* One EMDF payload directory entry. bit_offset is the MSB-first bit + * position of the payload's first byte inside the syncframe, exactly as the + * EMDF container syntax defines it (payloads are not byte aligned in general). */ +typedef struct joc_emdf_payload_info { + uint8_t id; + uint8_t reserved[3]; + uint16_t sample_offset; /* EMDF outer smpoffst, 11 bits */ + uint16_t reserved2; + uint32_t bit_offset; + uint32_t size; /* payload bytes */ +} joc_emdf_payload_info; + +typedef struct joc_emdf_info { + uint32_t struct_size; + uint32_t struct_version; + uint32_t start_bit; /* container syncword bit position */ + uint32_t container_bytes; /* 4 + declared length */ + uint32_t payload_count; + uint32_t reserved; + joc_emdf_payload_info payloads[JOC_MAX_EMDF_PAYLOADS]; +} joc_emdf_info; + +/* Per-object ID14/JOC descriptor plus its dequantized matrix. + * dq[dp][ch][pb] is zero filled outside [0,n_dpoints) x [0,n_channels) x + * [0,n_bands). Absent objects are entirely zero. */ +typedef struct joc_object_params { + uint8_t present; + uint8_t num_bands_idx; + uint8_t n_bands; + uint8_t sparse; /* 0 = dense (MTX), 1 = sparse (IDX+VEC) */ + uint8_t quant_idx; /* 0 = 96 levels, 1 = 192 levels */ + uint8_t slope_idx; /* 0 = interpolate, 1 = step at offset_ts */ + uint8_t num_dpoints_bits; + uint8_t n_dpoints; + uint8_t offset_ts[JOC_MAX_DPOINTS]; + uint8_t reserved[2]; + double dq[JOC_MAX_DPOINTS][JOC_MAX_CORE_CHANNELS][JOC_MAX_PARAMETER_BANDS]; +} joc_object_params; + +typedef struct joc_frame_params { + uint32_t struct_size; + uint32_t struct_version; + uint8_t dmx_config_idx; + uint8_t num_objects_bits; + uint8_t ext_config_idx; + uint8_t n_objects; + uint8_t n_channels; /* 5 or 7 */ + uint8_t clipgain_x_bits; + uint8_t clipgain_y_bits; + uint8_t objects_clamped; /* num_objects_bits+1 exceeded 15 */ + uint32_t seq_count; /* 10-bit JOC sequence counter, parsed only */ + uint32_t present_mask; /* bit i == object i present */ + uint32_t data_end_bits; /* bit position just after joc_data */ + uint32_t trailing_bits; /* bits left after joc_data (padding/ext) */ + uint8_t tail_bytes[8]; /* first up to 8 trailing bytes, for A/B */ + double clipgain; /* 1 + (y/32) * 2^(x-4), bit-exact */ + joc_object_params objects[JOC_MAX_OBJECTS]; +} joc_frame_params; + +/* Parse an EMDF ID14 (JOC) payload. */ +JOC_API joc_error JOC_CALL joc_parse_id14(const uint8_t* payload, size_t payload_size, + joc_frame_params* out_params); + +/* Locate the contiguous JOC EMDF container inside one E-AC-3 syncframe and + * parse its ID14 payload. out_emdf may be NULL. */ +JOC_API joc_error JOC_CALL joc_parse_eac3_frame(const uint8_t* frame, size_t frame_size, + joc_frame_params* out_params, + joc_emdf_info* out_emdf); + +/* Copy one payload's bytes out of a syncframe (MSB-first bit extraction, which + * equals a memcpy for byte-aligned containers). out_size receives the payload + * byte count; pass out == NULL to query only the size. */ +JOC_API joc_error JOC_CALL joc_extract_payload(const uint8_t* frame, size_t frame_size, + const joc_emdf_payload_info* payload, + uint8_t* out, size_t out_capacity, + size_t* out_size); + +/* E-AC-3 syncframe traversal: given the offset of a frame start, report its + * byte length so a host can walk a bare E-AC-3 stream without duplicating + * frmsiz logic. Rejects resynchronisation (no silent recovery). */ +JOC_API joc_error JOC_CALL joc_eac3_frame_bytes(const uint8_t* data, size_t size, + size_t offset, size_t* out_frame_bytes); + +/* Strict trailing-bit check for the JOC payload (A/B robustness corpus). + * Returns JOC_ERR_BITSTREAM_PADDING when more than 7 bits are left over or the + * leftover bits are not zero. */ +JOC_API joc_error JOC_CALL joc_check_id14_padding(const uint8_t* payload, size_t payload_size, + uint32_t* out_trailing_bits); + +/* ================================================================== */ +/* [T1] host tier: task, telemetry and control */ +/* ================================================================== */ + +/* ---- 1. events ---------------------------------------------------- */ +/* + * Events carry state only: frame/sample counters, stage, progress, statistics, + * warnings, errors and paths. Audio never travels through an event; a fixed + * size POD with no pointers keeps that enforceable (see the static assertion in + * the implementation). + */ +typedef enum joc_event_type { + JOC_EV_TASK_STARTED = 0x0001, + JOC_EV_TASK_STATE_CHANGED = 0x0002, + JOC_EV_TASK_COMPLETED = 0x0003, + JOC_EV_TASK_FAILED = 0x0004, + JOC_EV_TASK_CANCELLED = 0x0005, + JOC_EV_INPUT_OPENED = 0x0101, + JOC_EV_METADATA_INDEXED = 0x0103, + JOC_EV_HRTF_LOADED = 0x0110, + JOC_EV_RENDERER_INITIALIZED = 0x0120, + JOC_EV_PROGRESS = 0x0201, + JOC_EV_STAGE_CHANGED = 0x0202, + JOC_EV_JOC_FRAME_STATS = 0x0301, + JOC_EV_OAMD_STATS = 0x0302, + JOC_EV_OUTPUT_STATS = 0x0303, + JOC_EV_OUTPUT_OPENED = 0x0401, + JOC_EV_OUTPUT_FORMAT_DECIDED = 0x0402, + JOC_EV_OUTPUT_FINALIZED = 0x0403, + JOC_EV_LOG = 0x0501, + JOC_EV_WARNING = 0x0502, + JOC_EV_ERROR = 0x0503 +} joc_event_type; + +typedef enum joc_stage { + JOC_STAGE_IDLE = 0, + JOC_STAGE_INPUT = 1, + JOC_STAGE_METADATA = 2, + JOC_STAGE_DECODE = 3, + JOC_STAGE_JOC = 4, + JOC_STAGE_RENDER = 5, + JOC_STAGE_OUTPUT = 6, + JOC_STAGE_DONE = 7 +} joc_stage; + +enum { JOC_LOG_TRACE = 0, JOC_LOG_DEBUG = 1, JOC_LOG_INFO = 2, JOC_LOG_NOTICE = 3, + JOC_LOG_WARNING = 4, JOC_LOG_ERROR = 5, JOC_LOG_FATAL = 6 }; + +typedef struct joc_event { + uint32_t struct_size; + uint32_t type; + uint64_t sequence; + uint64_t timestamp_us; + uint64_t current_frame; + uint64_t total_frames; + uint64_t current_sample; + uint64_t total_samples; + uint32_t stage; + uint32_t backend; + double progress; /* 0..1, -1 = unknown */ + double elapsed_seconds; + double realtime_factor; + uint64_t output_samples; + uint64_t output_bytes; + double output_duration_seconds; + joc_error error_code; + uint32_t log_level; + char stage_name[32]; + char message[256]; +} joc_event; + +typedef void (JOC_CALL *joc_event_fn)(void* user, const joc_event* event); + +typedef struct joc_event_sink { + uint32_t struct_size; + joc_event_fn callback; + void* user; + uint32_t min_type; /* 0 = no filter */ + uint32_t max_type; /* 0 = no filter */ +} joc_event_sink; + +/* ---- 2. cancellation ---------------------------------------------- */ +typedef struct joc_cancel_token joc_cancel_token; + +JOC_API joc_cancel_token* JOC_CALL joc_cancel_token_create(void); +JOC_API void JOC_CALL joc_cancel_token_request(joc_cancel_token* token); +JOC_API int32_t JOC_CALL joc_cancel_token_is_requested(const joc_cancel_token* token); +JOC_API void JOC_CALL joc_cancel_token_destroy(joc_cancel_token* token); + +/* ---- 3. task configuration and results ---------------------------- */ +typedef enum joc_operation { + JOC_OP_ADM_BWF = 0, + JOC_OP_SPEAKER = 1, + JOC_OP_BINAURAL = 2 +} joc_operation; + +typedef enum joc_output_format { + JOC_FORMAT_FLOAT32 = 0, + JOC_FORMAT_PCM24 = 1 +} joc_output_format; + +typedef enum joc_binaural_mode { + JOC_BINAURAL_OFF = 0, + JOC_BINAURAL_NEAR = 1, + JOC_BINAURAL_FAR = 2, + JOC_BINAURAL_MID = 3 +} joc_binaural_mode; + +typedef enum joc_trajectory_mode { + JOC_TRAJECTORY_COMPACT = 0, + JOC_TRAJECTORY_DENSE64 = 1 +} joc_trajectory_mode; + +/* What to do when an int24 WAV would clip (peak outside [-1, 1]). Mirrors the + * reference CLI's --clip-action; ADM BWF output is always int24 and does not + * consult this because no alternative format exists there. */ +typedef enum joc_clip_action { + JOC_CLIP_ASK = 0, /* prompt on stdin; an error when stdin is not a terminal */ + JOC_CLIP_CONTINUE = 1, /* write int24, truncating out-of-range values */ + JOC_CLIP_FLOAT32 = 2, /* switch the output to float32 */ + JOC_CLIP_ABORT = 3 /* fail the task */ +} joc_clip_action; + +/* Compiled-HRTF cache policy for a SOFA input; the .jochrtf itself is an + * internal artifact of the compile step. */ +typedef enum joc_hrtf_cache_policy { + JOC_HRTF_CACHE_NONE = 0, /* compile and discard */ + JOC_HRTF_CACHE_MEMORY = 1, /* compile and keep in this process (default) */ + JOC_HRTF_CACHE_DISK = 2 /* compile, reuse and write /.jochrtf */ +} joc_hrtf_cache_policy; + +enum { JOC_TASK_F_SKIP_SHA256 = 1u, JOC_TASK_F_KEEP_INTERMEDIATE = 2u, + JOC_TASK_F_QUIET = 4u, JOC_TASK_F_METADATA_ONLY = 8u }; + +typedef struct joc_task_config { + uint32_t struct_size; + uint32_t struct_version; + + /* input */ + const char* input_path; /* .eac3/.ec3/.m4a/... */ + const char* ffmpeg_path; /* NULL = FFMPEG, then "ffmpeg" on PATH */ + const char* bed_path; /* NULL = decode the core PCM with ffmpeg */ + const char* work_dir; /* NULL = a temporary directory */ + double eac3_drc_scale; /* 0 = DRC off (reference default) */ + int32_t eac3_target_level; /* -31..0, 0 = not applied */ + + /* output */ + uint32_t operation; + const char* output_path; + uint32_t output_format; /* requested format for speaker/binaural */ + uint32_t flags; + uint32_t clip_action; /* joc_clip_action; JOC_CLIP_ASK by default */ + + /* rendering */ + const char* speaker_layout_name; + uint32_t speaker_metadata_offset; /* default 1473 */ + uint32_t binaural_mode; + const char* hrtf_path; /* .jochrtf */ + const char* kernels_path; /* rosella_kernels.npz */ + double binaural_tail_seconds; /* default 5.0 */ + double binaural_tail_threshold; /* binaural only; 0 disables trimming */ + uint32_t binaural_chunk_frames; /* accepted for CLI parity; no effect */ + + /* ADM */ + uint32_t adm_binaural_mode; /* DBMD segment 10 encoding */ + uint32_t trajectory_mode; + + /* generic */ + uint32_t object_delay_samples; /* default 1473 */ + double gain_db; /* default 0 */ + uint64_t duration_frames; /* 0 = the whole stream */ + uint32_t progress_interval_frames; /* default 1000 */ + uint32_t native_threads; /* 0 = automatic */ + + /* diagnostics */ + uint32_t print_metadata; /* 0 none, 1 summary, 2 per frame */ + const char* metadata_json_path; /* NULL = no JSON summary */ + + joc_cancel_token* cancel; /* optional */ + + /* Binaural HRTF input (config version 2): when hrtf_sofa_path is set the + * library compiles it with hrtf_cache_policy / hrtf_cache_dir / hrtf_radius_m + * and hrtf_path is unused. hrtf_path stays the advanced override that reads + * a .jochrtf directly. */ + const char* hrtf_sofa_path; /* SOFA SimpleFreeFieldHRIR input */ + const char* personalized_headphone_path; /* Rosella .personalized_headphone input */ + const char* hrtf_cache_dir; /* disk policy directory */ + uint32_t hrtf_cache_policy; /* joc_hrtf_cache_policy */ + uint32_t reserved0; + double hrtf_radius_m; /* SOFA measurement-radius shell */ +} joc_task_config; + +typedef enum joc_task_status { + JOC_TASK_OK = 0, + JOC_TASK_FAILED = 1, + JOC_TASK_CANCELLED = 2 +} joc_task_status; + +typedef struct joc_task_result { + uint32_t struct_size; + uint32_t struct_version; + uint32_t status; + uint32_t error_code; + char error_message[512]; + char error_stage[32]; + uint64_t input_frames; + uint64_t output_samples; + double duration_sec; + uint32_t output_format_actual; + double output_peak; + uint64_t output_over_unity_values; + uint64_t output_file_bytes; + char output_sha256[65]; /* empty when skipped */ + uint64_t oamd_payloads; + uint64_t oamd_transitions; + double t_decode_bed; + double t_render; + double t_write; + double t_total; + double t_render_dsp; /* speaker/binaural DSP calls only; 0 for ADM */ + double t_write_file; /* disk writes including the finalize; >= t_write */ +} joc_task_result; + +typedef struct joc_validation_issue { + joc_error code; + uint32_t severity; /* 0 = info, 1 = warning, 2 = error */ + char field[48]; + char message[256]; +} joc_validation_issue; + +/* ---- 4. entry points ---------------------------------------------- */ +/* Fills `issues` (up to `capacity`) and reports how many were produced. + * Returns JOC_OK when no *error*-severity issue was found. */ +JOC_API joc_error JOC_CALL joc_task_validate(const joc_task_config* config, + joc_validation_issue* issues, uint32_t capacity, + uint32_t* count); + +/* Runs the whole task on the calling thread. `sink` may be NULL; `out` may be + * NULL. On cancellation the partial output is removed and JOC_ERR_CANCELLED is + * returned with out->status = JOC_TASK_CANCELLED. */ +JOC_API joc_error JOC_CALL joc_task_execute(const joc_task_config* config, + const joc_event_sink* sink, joc_task_result* out); + +/* Serialises the stable subset of the result as JSON (no environment fields - + * those belong to the frontend). `needed` receives the required size including + * the terminator; a NULL buffer queries only the size. */ +JOC_API joc_error JOC_CALL joc_task_result_to_json(const joc_task_result* result, char* buffer, + size_t capacity, size_t* needed); + +/* The streaming (push/pull) tier lives in "joc_stream.h" so an embedder can + * include the narrow surface without the bitstream/verification tier. */ + +#ifdef __cplusplus +} /* extern "C" */ +#endif diff --git a/fork/files/audio/decode/joc_eac3.c b/fork/files/audio/decode/joc_eac3.c new file mode 100644 index 0000000..ab48131 --- /dev/null +++ b/fork/files/audio/decode/joc_eac3.c @@ -0,0 +1,100 @@ +/* + * MIT License, Copyright (c) 2026 TheM14 + * + * Derived from the upstream project's eac3_scan.cpp (JustOneCacophony), + * rewritten in C. + * See LICENSE-MIT. + */ + +#include + +#include "audio/decode/joc_eac3.h" + +#define EAC3_SYNCWORD 0x0B77u + +static uint32_t read_bits(const uint8_t *data, size_t start, size_t count) +{ + uint32_t value = 0; + for (size_t index = start; index < start + count; ++index) + value = (value << 1) | ((data[index >> 3] >> (7u - (index & 7u))) & 1u); + return value; +} + +/* AC-3 syncframe length in 16-bit words, indexed by fscod then frmsizecod. */ +static const uint16_t ac3_frame_words[3][38] = { + {64, 64, 80, 80, 96, 96, 112, 112, 128, 128, 160, 160, 192, 192, 224, 224, + 256, 256, 320, 320, 384, 384, 448, 448, 512, 512, 640, 640, 768, 768, + 896, 896, 1024, 1024, 1152, 1152, 1280, 1280}, + {69, 70, 87, 88, 104, 105, 121, 122, 139, 140, 174, 175, 208, 209, 243, 244, + 278, 278, 348, 348, 417, 418, 487, 487, 557, 557, 696, 696, 835, 835, + 975, 975, 1114, 1114, 1253, 1253, 1393, 1393}, + {96, 96, 120, 120, 144, 144, 168, 168, 192, 192, 240, 240, 288, 288, 336, 336, + 384, 384, 480, 480, 576, 576, 672, 672, 768, 768, 960, 960, 1152, 1152, + 1344, 1344, 1536, 1536, 1728, 1728, 1920, 1920}, +}; + +size_t joc_eac3_frame_header_at(const uint8_t *data, size_t size, size_t offset, + struct joc_eac3_header *out) +{ + if (!data || offset + 6u > size) + return 0; + uint16_t syncword = (uint16_t)((data[offset] << 8) | data[offset + 1]); + if (syncword != EAC3_SYNCWORD) + return 0; + size_t base = offset * 8u; + uint32_t bsid = read_bits(data, base + 40u, 5u); + if (bsid <= 8u) { + uint32_t fscod = read_bits(data, base + 32u, 2u); + uint32_t frmsizecod = read_bits(data, base + 34u, 6u); + if (fscod > 2u || frmsizecod >= 38u) + return 0; + size_t bytes = (size_t)ac3_frame_words[fscod][frmsizecod] * 2u; + if (out) { + out->frame_bytes = bytes; + out->offset = offset; + out->codec = 0; + out->strmtyp = 0; + out->substreamid = 0; + } + return bytes; + } + size_t words = ((size_t)(data[offset + 2] & 0x07u) << 8) | data[offset + 3]; + size_t bytes = (words + 1u) * 2u; + if (out) { + out->frame_bytes = bytes; + out->offset = offset; + out->codec = 1; + out->strmtyp = (uint8_t)read_bits(data, base + 16u, 2u); + out->substreamid = (uint8_t)read_bits(data, base + 18u, 3u); + } + return bytes; +} + +size_t joc_eac3_audio_frame_bytes(const uint8_t *data, size_t size, size_t offset, + int end_of_stream) +{ + struct joc_eac3_header seen[8]; + size_t count = 0; + size_t consumed = 0; + while (count < 8) { + struct joc_eac3_header header; + size_t bytes = joc_eac3_frame_header_at(data, size, offset + consumed, &header); + if (bytes == 0 || offset + consumed + bytes > size) + break; + int repeats = 0; + for (size_t index = 0; index < count; ++index) { + if (seen[index].codec == header.codec && seen[index].strmtyp == header.strmtyp && + seen[index].substreamid == header.substreamid) { + repeats = 1; + break; + } + } + if (repeats) + return consumed; + seen[count++] = header; + consumed += bytes; + } + if (count != 0u && consumed != 0u && end_of_stream) + return consumed; + return 0; +} diff --git a/fork/files/audio/decode/joc_eac3.h b/fork/files/audio/decode/joc_eac3.h new file mode 100644 index 0000000..0df3989 --- /dev/null +++ b/fork/files/audio/decode/joc_eac3.h @@ -0,0 +1,40 @@ +/* + * MIT License, Copyright (c) 2026 TheM14 + * + * Derived from the upstream project's eac3_scan.cpp (JustOneCacophony), + * rewritten in C. + * See LICENSE-MIT. + */ + +/* E-AC-3 syncframe walking, sized for the audio decoder in ad_joc.c. + * + * An E-AC-3 "audio frame" can be more than one syncframe: a 7-channel JOC + * program interleaves an independent and a dependent substream, and the + * renderer pairs one whole audio frame with one 1536-sample bed frame. These + * helpers are a C port of the subset of the upstream eac3_scan.cpp that the + * decoder needs (no EMDF/JOC inspection: the renderer itself validates that). + */ +#pragma once + +#include +#include + +struct joc_eac3_header { + size_t frame_bytes; + size_t offset; + uint8_t codec; /* 0 = AC-3, 1 = E-AC-3 */ + uint8_t strmtyp; + uint8_t substreamid; +}; + +/* Length of the syncframe at data[offset], or 0 when there is no valid header. + * AC-3 and E-AC-3 are told apart by bsid, exactly as the renderer does. */ +size_t joc_eac3_frame_header_at(const uint8_t *data, size_t size, size_t offset, + struct joc_eac3_header *out); + +/* Length of the whole audio frame at data[offset]: every syncframe up to the + * first repeated (codec, strmtyp, substreamid). Returns 0 while the group is + * still open inside the buffer, unless end_of_stream says no more bytes will + * arrive. */ +size_t joc_eac3_audio_frame_bytes(const uint8_t *data, size_t size, size_t offset, + int end_of_stream); diff --git a/fork/files/audio/decode/joc_stream.h b/fork/files/audio/decode/joc_stream.h new file mode 100644 index 0000000..5c2076b --- /dev/null +++ b/fork/files/audio/decode/joc_stream.h @@ -0,0 +1,146 @@ +/* + * joc_stream.h -- streaming (push/pull) interface of the JustOneCacophony core. + * + * This is the narrow, embedder-facing surface: a player or decoder component + * includes only this header. It is the same shared library as joc_core.h, split + * so an integrator never has to see the bitstream/verification tier. + * + * A stream is a stateful instance for hosts that cannot wait for a whole file: + * the caller feeds E-AC-3 bytes and the core PCM of the same frames (or already + * rebuilt objects16) and pulls rendered PCM as soon as it is available. It + * mirrors the two library shapes a decoder library normally offers: this + * push/pull form for host-owned I/O, and joc_task_execute() in joc_core.h for + * library-owned file I/O. + * + * Contract: + * - all state is instance-private, so several streams coexist; + * - a stream is NOT thread safe: push and pull must come from one thread; + * - rendering is stateful (matrix interpolation, gain ramps, room tail), so a + * new position on the timeline requires decoding to continue from the start + * of the stream; there is no seek in this version; + * - the kernel latency is 961 samples for speaker/binaural output: the first + * pull after two 512-sample blocks, and flush() drains the binaural tail. + */ +#pragma once + +#include "joc_core.h" + +/* JOC_STATIC (building the sources directly into an application): joc_core.h above already installs the empty JOC_API. */ +#if defined(JOC_STATIC) && !defined(JOC_API) + #define JOC_API + #define JOC_CALL __cdecl +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct joc_stream joc_stream; + +typedef enum joc_stream_input { + JOC_STREAM_IN_EAC3 = 0, /* bare E-AC-3 syncframes (the metadata stream) */ + JOC_STREAM_IN_PCM_OBJECTS16 = 1, /* objects16 frames, planar [16][1536] each */ + JOC_STREAM_IN_CORE_PCM = 3 /* the 5.1 core PCM of the pushed E-AC-3 frames */ +} joc_stream_input; + +typedef enum joc_stream_output { + JOC_STREAM_OUT_PCM_OBJECTS16 = 0, /* objects16 frames, planar [16][1536] each */ + JOC_STREAM_OUT_SPEAKER = 1, /* interleaved [samples][channels] f32 */ + JOC_STREAM_OUT_BINAURAL = 2 /* interleaved [samples][2] f32 */ +} joc_stream_output; + +typedef struct joc_stream_config { + uint32_t struct_size; + uint32_t struct_version; + uint32_t input; + uint32_t output; + const char* speaker_layout_name; + uint32_t speaker_metadata_offset; /* default 1473 */ + uint32_t binaural_mode; /* near|mid|far; 0 means mid */ + const char* hrtf_path; /* binaural only */ + const char* kernels_path; /* binaural only */ + double binaural_tail_seconds; /* default 5.0 */ + uint32_t object_delay_samples; /* default 1473 */ + double gain_db; /* default 0 */ + uint32_t native_threads; + uint32_t reserved; + /* Binaural HRTF input, the same three shapes joc_task_config accepts: when + * hrtf_sofa_path is set the library compiles it with hrtf_cache_policy / + * hrtf_cache_dir / hrtf_radius_m and hrtf_path is unused; when + * personalized_headphone_path is set the Rosella runtime renders instead. + * hrtf_path stays the fallback/advanced input that reads a .jochrtf directly. */ + const char* hrtf_sofa_path; /* SOFA SimpleFreeFieldHRIR input */ + const char* personalized_headphone_path; /* Rosella .personalized_headphone input */ + const char* hrtf_cache_dir; /* disk cache directory for SOFA compilation */ + uint32_t hrtf_cache_policy; /* joc_hrtf_cache_policy: 0 none, 1 memory, 2 disk */ + double hrtf_radius_m; /* SOFA measurement-radius shell, default 1.0 */ +} joc_stream_config; + +typedef struct joc_stream_buffer { + uint32_t struct_size; + uint32_t struct_version; + uint32_t kind; /* which joc_stream_input/output this buffer carries */ + uint32_t channels; + uint32_t sample_rate; + uint32_t sample_count; /* in: capacity / out: produced (per channel) */ + uint32_t byte_count; /* in: capacity / out: consumed or produced bytes */ + uint32_t reserved; + const uint8_t* bytes; /* EAC3 input */ + const float* pcm; /* PCM input */ + uint8_t* out_bytes; /* reserved for encoded outputs */ + float* out_pcm; /* PCM output */ +} joc_stream_buffer; + +typedef struct joc_stream_status_info { + uint32_t struct_size; + uint32_t struct_version; + uint64_t frames_in; + uint64_t frames_out; + uint64_t samples_in; + uint64_t samples_out; + uint64_t bytes_in; + uint64_t buffered_samples; /* rendered but not yet pulled, per channel */ + uint64_t oamd_payloads; + uint64_t oamd_transitions; + /* Metadata the renderer had to work around, per audio frame: no JOC payload at + * all, a declared object count clamped to 15, and a syncframe carrying a second + * EMDF container that is not this frame's JOC metadata. */ + uint64_t missing_joc_frames; + uint64_t objects_clamped_frames; + uint64_t extra_container_frames; + /* Extra-pair identity disagreements across layers (spec 11.2 checks 1 and 2). + * The identity is metadata only, so those frames still render. */ + uint64_t chanmap_pair_mismatch_frames; + uint64_t bed_mask_mismatch_frames; + uint32_t output_channels; + uint32_t ended; /* 1 after flush() */ +} joc_stream_status_info; + +JOC_API joc_error JOC_CALL joc_stream_create(const joc_stream_config* config, joc_stream** out); + +/* Feeds one buffer. Kind selects the path: EAC3 bytes, the core PCM of those + * frames, or objects16. Consumed counts are reported so a caller can resume + * from a partial push. */ +JOC_API joc_error JOC_CALL joc_stream_push(joc_stream* stream, const joc_stream_buffer* input, + uint32_t* consumed_samples, uint32_t* consumed_bytes); + +/* Copies as many rendered samples as fit into `output` (interleaved, or planar + * for PCM_OBJECTS16) and reports how many were produced; 0 means "push more". */ +JOC_API joc_error JOC_CALL joc_stream_pull(joc_stream* stream, joc_stream_buffer* output, + uint32_t* produced_samples); + +/* Marks the end of input and drains whatever the renderer still holds (the + * binaural room tail); pull the remaining samples afterwards. */ +JOC_API joc_error JOC_CALL joc_stream_flush(joc_stream* stream); + +/* Returns the instance to its initial state (kernel, ramps, timeline, room, + * parser, counters) so the same stream can be reused for another pass. */ +JOC_API joc_error JOC_CALL joc_stream_reset(joc_stream* stream); + +JOC_API joc_error JOC_CALL joc_stream_status(const joc_stream* stream, + joc_stream_status_info* out); +JOC_API joc_error JOC_CALL joc_stream_destroy(joc_stream* stream); + +#ifdef __cplusplus +} /* extern "C" */ +#endif diff --git a/fork/files/audio/decode/joc_version.h b/fork/files/audio/decode/joc_version.h new file mode 100644 index 0000000..809f69b --- /dev/null +++ b/fork/files/audio/decode/joc_version.h @@ -0,0 +1,16 @@ +/* Product version of joc_core and joc_cli. + * + * This file is the single source of truth: CMakeLists.txt reads these numbers for + * project(VERSION ...), joc_version_string() returns JOC_VERSION_STRING, and the + * release workflow refuses a tag that does not match it. Bump the three numbers + * and the string together, then tag the commit with v. + */ +#ifndef JOC_VERSION_H +#define JOC_VERSION_H + +#define JOC_VERSION_MAJOR 1 +#define JOC_VERSION_MINOR 0 +#define JOC_VERSION_PATCH 0 +#define JOC_VERSION_STRING "1.0.0" + +#endif /* JOC_VERSION_H */ diff --git a/fork/mpv.conf.example b/fork/mpv.conf.example new file mode 100644 index 0000000..c4de1f8 --- /dev/null +++ b/fork/mpv.conf.example @@ -0,0 +1,28 @@ +# ad_joc: E-AC-3 JOC through the JustOneCacophony renderer. +# Copy the lines you need into mpv.conf; all of them are ordinary mpv options. + +ad = joc + +# Binaural (stereo) output. On by default; "no" renders the speaker layout below. +ad-joc-binaural = yes + +# HRTF input: SOFA, a Rosella .personalized_headphone, or a compiled .jochrtf. +# The kind is detected from the file, so do not name it here. +# Leave empty to search /HRTF/binaural.sofa, then the same names under +# the mpv config dir. +ad-joc-hrtf = + +# Speaker layout, used when ad-joc-binaural=no (and as the fallback when no +# HRTF can be found; mpv then downmixes it to whatever the device wants). +# 2.0 3.0 3.1 4.0 5.0 5.1 5.1.2 5.1.4 6.1 7.0 7.1 7.1.2 7.1.4 9.1.4 9.1.6 +ad-joc-layout = 7.1 + +# Binaural rendering mode: near | mid | far. +ad-joc-mode = mid + +# Extra gain in dB (-60 .. 12). +ad-joc-gain-db = 0 + +# Quantise the output to the renderer's 24-bit rule (the same truncation +# the renderer's own frontends deliver in int24 mode). Off = plain float32. +ad-joc-int24 = no diff --git a/fork/patches/mpv-ad-joc.patch b/fork/patches/mpv-ad-joc.patch new file mode 100644 index 0000000..d7b077d --- /dev/null +++ b/fork/patches/mpv-ad-joc.patch @@ -0,0 +1,136 @@ +diff --git a/filters/f_decoder_wrapper.c b/filters/f_decoder_wrapper.c +index 2397c85..c0650b8 100644 +--- a/filters/f_decoder_wrapper.c ++++ b/filters/f_decoder_wrapper.c +@@ -419,6 +419,20 @@ struct mp_decoder_list *audio_decoder_list(void) + return list; + } + ++static bool decoder_name_listed(const char *list, const char *name) ++{ ++ if (!list) ++ return false; ++ bstr sel = bstr0(list); ++ while (sel.len) { ++ bstr item; ++ bstr_split_tok(sel, ",", &item, &sel); ++ if (bstr_equals0(item, name)) ++ return true; ++ } ++ return false; ++} ++ + static bool reinit_decoder(struct priv *p) + { + if (p->decoder) +@@ -464,6 +478,26 @@ static bool reinit_decoder(struct priv *p) + } + } + } ++ ++#if HAVE_JOC ++ /* E-AC-3 JOC through the JustOneCacophony core: --ad=joc renders the ++ * objects (binaural or a speaker layout) instead of letting FFmpeg ++ * downmix. Opt-in, so default playback is untouched. */ ++ if (driver == &ad_lavc && p->codec->codec && ++ strcmp(p->codec->codec, "eac3") == 0 && ++ decoder_name_listed(user_list, "joc")) ++ { ++ struct mp_decoder_list *joc_list = ++ talloc_zero(NULL, struct mp_decoder_list); ++ ad_joc.add_decoders(joc_list); ++ if (joc_list->num_entries) { ++ driver = &ad_joc; ++ list = joc_list; ++ } else { ++ talloc_free(joc_list); ++ } ++ } ++#endif + } + + if (!driver) +diff --git a/filters/f_decoder_wrapper.h b/filters/f_decoder_wrapper.h +index b39d3f5..c668c4e 100644 +--- a/filters/f_decoder_wrapper.h ++++ b/filters/f_decoder_wrapper.h +@@ -113,6 +113,7 @@ extern const struct mp_decoder_fns vd_lavc; + extern const struct mp_decoder_fns ad_lavc; + extern const struct mp_decoder_fns ad_spdif; + extern const struct mp_decoder_fns ad_dsd; ++extern const struct mp_decoder_fns ad_joc; + + // Convenience wrapper for lavc based decoders. Treat lavc_state as private; + // init to all-0 on init and resets. +diff --git a/meson.build b/meson.build +index 4574234..45a39fb 100644 +--- a/meson.build ++++ b/meson.build +@@ -1771,10 +1771,22 @@ if rst2pdf.found() + endif + + ++# E-AC-3 JOC decoder (ad_joc): links the JustOneCacophony rendering core. ++joc_core_dir = get_option('joc-core-dir') ++if joc_core_dir != '' ++ joc_core = cc.find_library('joc_core', dirs: [joc_core_dir], required: true) ++ dependencies += joc_core ++ sources += files('audio/decode/ad_joc.c', 'audio/decode/joc_eac3.c') ++ joc_enabled = 1 ++else ++ joc_enabled = 0 ++endif ++ + # Set config.h + conf_data = configuration_data() + conf_data.set_quoted('CONFIGURATION', meson.build_options().strip().replace('\\', '\\\\')) + conf_data.set_quoted('DEFAULT_OPTICAL_DEVICE', optical_device) ++conf_data.set('HAVE_JOC', joc_enabled) + + # Loop over all features in the build, create a define and add them to config.h + feature_keys = [] +diff --git a/meson.options b/meson.options +index 3211082..4f539b6 100644 +--- a/meson.options ++++ b/meson.options +@@ -1,5 +1,6 @@ + # booleans + option('gpl', type: 'boolean', value: true, description: 'GPL (version 2 or later) build') ++option('joc-core-dir', type: 'string', value: '', description: 'Directory holding joc_core.lib: builds the E-AC-3 JOC decoder (ad_joc)') + option('cplayer', type: 'boolean', value: true, description: 'mpv CLI player') + option('libmpv', type: 'boolean', value: true, description: 'libmpv library') + option('build-date', type: 'boolean', value: true, description: 'include compile timestamp in binary') +diff --git a/options/options.c b/options/options.c +index e8b590a..a575bd8 100644 +--- a/options/options.c ++++ b/options/options.c +@@ -76,6 +76,7 @@ extern const struct m_sub_options demux_sbr_conf; + #endif + extern const struct m_sub_options vd_lavc_conf; + extern const struct m_sub_options ad_lavc_conf; ++extern const struct m_sub_options ad_joc_conf; + extern const struct m_sub_options hwdec_conf; + extern const struct m_sub_options input_config; + extern const struct m_sub_options encode_config; +@@ -713,6 +714,9 @@ static const m_option_t mp_opts[] = { + {"", OPT_SUBSTRUCT(dec_wrapper, dec_wrapper_conf)}, + {"", OPT_SUBSTRUCT(vd_lavc_params, vd_lavc_conf)}, + {"ad-lavc", OPT_SUBSTRUCT(ad_lavc_params, ad_lavc_conf)}, ++#if HAVE_JOC ++ {"ad-joc", OPT_SUBSTRUCT(ad_joc_params, ad_joc_conf)}, ++#endif + + {"", OPT_SUBSTRUCT(hwdec_opts, hwdec_conf)}, + +diff --git a/options/options.h b/options/options.h +index 26a7913..f88629c 100644 +--- a/options/options.h ++++ b/options/options.h +@@ -394,6 +394,7 @@ typedef struct MPOpts { + + struct vd_lavc_params *vd_lavc_params; + struct ad_lavc_params *ad_lavc_params; ++ struct ad_joc_params *ad_joc_params; + + struct hwdec_opts *hwdec_opts; + diff --git a/fork/tools/apply_edits.py b/fork/tools/apply_edits.py new file mode 100644 index 0000000..65245d7 --- /dev/null +++ b/fork/tools/apply_edits.py @@ -0,0 +1,177 @@ +#!/usr/bin/env python3 +"""Apply the ad_joc integration to an mpv source tree by anchors. + +A unified diff breaks when upstream moves lines around; this edits the same +six places by their surrounding text instead, and is idempotent, so it can be +re-run on any mpv revision. If an anchor is gone, the call fails before +touching anything: that is the moment a human has to look at what upstream +changed. + +Usage: apply_edits.py +""" +import os +import sys + +MESON_OPTION = ("option('joc-core-dir', type: 'string', value: '', " + "description: 'Directory holding joc_core.lib: builds the E-AC-3 JOC decoder (ad_joc)')") + +MESON_BLOCK = """# E-AC-3 JOC decoder (ad_joc): links the JustOneCacophony rendering core. +joc_core_dir = get_option('joc-core-dir') +if joc_core_dir != '' + joc_core = cc.find_library('joc_core', dirs: [joc_core_dir], required: true) + dependencies += joc_core + sources += files('audio/decode/ad_joc.c', 'audio/decode/joc_eac3.c') + joc_enabled = 1 +else + joc_enabled = 0 +endif""" + +WRAPPER_HELPER = """static bool decoder_name_listed(const char *list, const char *name) +{ + if (!list) + return false; + bstr sel = bstr0(list); + while (sel.len) { + bstr item; + bstr_split_tok(sel, ",", &item, &sel); + if (bstr_equals0(item, name)) + return true; + } + return false; +}""" + +WRAPPER_BLOCK = """#if HAVE_JOC + /* E-AC-3 JOC through the JustOneCacophony core: --ad=joc renders the + * objects (binaural or a speaker layout) instead of letting FFmpeg + * downmix. Opt-in, so default playback is untouched. */ + if (driver == &ad_lavc && p->codec->codec && + strcmp(p->codec->codec, "eac3") == 0 && + decoder_name_listed(user_list, "joc")) + { + struct mp_decoder_list *joc_list = + talloc_zero(NULL, struct mp_decoder_list); + ad_joc.add_decoders(joc_list); + if (joc_list->num_entries) { + driver = &ad_joc; + list = joc_list; + } else { + talloc_free(joc_list); + } + } +#endif""" + + +class Tree: + def __init__(self, root): + self.root = root + self.orig = {} + self.text = {} + + def read(self, rel): + path = os.path.join(self.root, rel) + # Universal newlines: the tool works on LF and writes LF back, which is + # what the mpv tree uses; git normalises the rest. + with open(path, "r", encoding="utf-8") as f: + s = f.read() + self.orig[rel] = s + self.text[rel] = s + return s + + def put(self, rel, s): + self.text[rel] = s + + def write_all(self): + for rel, s in self.text.items(): + if s != self.orig.get(rel): + with open(os.path.join(self.root, rel), "w", encoding="utf-8", newline="\n") as f: + f.write(s) + + +def eol_of(s): + return "\r\n" if "\r\n" in s[:2000] else "\n" + + +def add_after(tree, rel, anchor, block, what): + s = tree.text[rel] + if block.strip() in s: + return + i = s.find(anchor) + if i < 0: + raise SystemExit("%s: anchor for %s not found" % (rel, what)) + eol = eol_of(s) + j = i + len(anchor) + tree.put(rel, s[:j] + eol + block.replace("\n", eol) + s[j:]) + + +def add_before(tree, rel, anchor, block, what): + s = tree.text[rel] + if block.strip() in s: + return + i = s.find(anchor) + if i < 0: + raise SystemExit("%s: anchor for %s not found" % (rel, what)) + eol = eol_of(s) + tree.put(rel, s[:i] + block.replace("\n", eol) + eol + s[i:]) + + +def main(): + root = sys.argv[1] if len(sys.argv) > 1 else "." + tree = Tree(root) + + for rel in ("meson.options", "meson.build", "filters/f_decoder_wrapper.c", + "filters/f_decoder_wrapper.h", "options/options.c", "options/options.h"): + tree.read(rel) + + add_after(tree, "meson.options", + "option('gpl', type: 'boolean', value: true, description: 'GPL (version 2 or later) build')", + MESON_OPTION, "gpl option") + add_before(tree, "meson.build", "# Set config.h", MESON_BLOCK, "config.h marker") + add_after(tree, "meson.build", + "conf_data.set_quoted('DEFAULT_OPTICAL_DEVICE', optical_device)", + "conf_data.set('HAVE_JOC', joc_enabled)", "conf_data") + + add_after(tree, "filters/f_decoder_wrapper.c", '#include "common/msg.h"', + '#include "misc/bstr.h"', "bstr include") + add_before(tree, "filters/f_decoder_wrapper.c", + "static bool reinit_decoder(struct priv *p)", WRAPPER_HELPER, "reinit_decoder") + s = tree.text["filters/f_decoder_wrapper.c"] + i = s.find("static bool reinit_decoder(struct priv *p)") + j = s.find("\n if (!driver)", i) + if j < 0: + raise SystemExit("filters/f_decoder_wrapper.c: if (!driver) not found") + if WRAPPER_BLOCK.strip() not in s: + eol = eol_of(s) + # Insert inside the audio branch: the last " }" before if (!driver) + # closes it, and the block belongs before that brace. + k = s.rfind("\n }", i, j) + if k < 0: + raise SystemExit("filters/f_decoder_wrapper.c: audio branch brace not found") + pos = k + 1 + tree.put("filters/f_decoder_wrapper.c", + s[:pos] + WRAPPER_BLOCK.replace("\n", eol) + eol + s[pos:]) + + add_after(tree, "filters/f_decoder_wrapper.h", + "extern const struct mp_decoder_fns ad_dsd;", + "extern const struct mp_decoder_fns ad_joc;", "ad_dsd extern") + add_after(tree, "options/options.c", + "extern const struct m_sub_options ad_lavc_conf;", + "extern const struct m_sub_options ad_joc_conf;", "ad_lavc_conf extern") + s = tree.text["options/options.c"] + if '"ad-joc", OPT_SUBSTRUCT' not in s: + eol = eol_of(s) + anchor = ' {"ad-lavc", OPT_SUBSTRUCT(ad_lavc_params, ad_lavc_conf)},' + i = s.find(anchor) + if i < 0: + raise SystemExit("options/options.c: ad-lavc option not found") + block = "#if HAVE_JOC" + eol + ' {"ad-joc", OPT_SUBSTRUCT(ad_joc_params, ad_joc_conf)},' + eol + "#endif" + tree.put("options/options.c", s[:i + len(anchor)] + eol + block + s[i + len(anchor):]) + add_after(tree, "options/options.h", + " struct ad_lavc_params *ad_lavc_params;", + " struct ad_joc_params *ad_joc_params;", "ad_lavc field") + + tree.write_all() + print("apply_edits: mpv tree updated") + + +if __name__ == "__main__": + main() diff --git a/fork/tools/build_fork.ps1 b/fork/tools/build_fork.ps1 new file mode 100644 index 0000000..e02913d --- /dev/null +++ b/fork/tools/build_fork.ps1 @@ -0,0 +1,62 @@ +# Build a patched mpv from a clean mpv checkout. +# +# .\tools\build_fork.ps1 # latest master, full build +# .\tools\build_fork.ps1 -MpvRef v0.41.0 # a tag instead +# .\tools\build_fork.ps1 -SkipBuild # only clone + apply +# +# The mpv tree is cloned once into -WorkDir and then reused; the edits come +# from tools\apply_edits.py, which anchors on surrounding code instead of line +# numbers, so it keeps working across mpv revisions. +param( + [string]$MpvRef = "master", + [string]$WorkDir = (Join-Path $PSScriptRoot "..\..\..\_forkwork"), + [string]$MsysRoot = $(if ($env:MSYS2_ROOT) { $env:MSYS2_ROOT } else { "C:\msys64" }), + [string]$JocCoreDir = (Join-Path $PSScriptRoot "..\..\build\joc_core\Release"), + [switch]$SkipBuild +) + +$ErrorActionPreference = "Stop" +$repo = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path +$mpv = Join-Path $WorkDir "mpv" + +New-Item -ItemType Directory -Force -Path $WorkDir | Out-Null +if (-not (Test-Path (Join-Path $mpv ".git"))) { + git clone --depth 1 --branch $MpvRef https://github.com/mpv-player/mpv.git $mpv + if ($LASTEXITCODE -ne 0) { throw "git clone failed" } +} else { + git -C $mpv fetch --depth 1 origin $MpvRef + git -C $mpv checkout -f FETCH_HEAD + if ($LASTEXITCODE -ne 0) { throw "git checkout failed" } +} +git -C $mpv reset --hard | Out-Null +Write-Host ("mpv: " + (git -C $mpv log -1 --format='%h %cd %s' --date=short)) + +Copy-Item (Join-Path $repo "files\audio\decode\*") (Join-Path $mpv "audio\decode\") -Force +python (Join-Path $PSScriptRoot "apply_edits.py") $mpv +if ($LASTEXITCODE -ne 0) { throw "apply_edits.py failed" } + +if ($SkipBuild) { Write-Host "patched tree: $mpv"; exit 0 } + +$bash = Join-Path $MsysRoot "usr\bin\bash.exe" +if (-not (Test-Path $bash)) { + throw "MSYS2 not found at $MsysRoot; pass -MsysRoot or set MSYS2_ROOT" +} +$mpvU = $mpv -replace '\\','/' +$coreU = $JocCoreDir -replace '\\','/' +$lines = @( + 'set -e', + 'export PATH=/mingw64/bin:/usr/bin:$PATH', + 'export MSYSTEM=MINGW64', + "cd $mpvU", + 'rm -rf build', + "meson setup build --buildtype=release -Dgpl=false -Dlua=luajit -Djoc-core-dir=$coreU", + 'ninja -C build' +) +$shell = $lines -join [Environment]::NewLine +$shell | & $bash -lc "cat > /tmp/build_fork.sh && bash /tmp/build_fork.sh" +if ($LASTEXITCODE -ne 0) { throw "build failed" } + +$bundle = ($repo -replace '\\','/') + "/tools/bundle_dlls.sh" +& $bash -lc "'$bundle' '$mpvU/build'" +Copy-Item (Join-Path $JocCoreDir "joc_core.dll") (Join-Path $mpv "build") -Force +Write-Host ("built: " + (Join-Path $mpv "build\mpv.exe")) diff --git a/fork/tools/bundle_dlls.sh b/fork/tools/bundle_dlls.sh new file mode 100644 index 0000000..caa47f8 --- /dev/null +++ b/fork/tools/bundle_dlls.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# Copy the MinGW runtime DLL closure of mpv.exe next to it, so the build runs +# without the MSYS2 environment on PATH. +# +# Usage: bundle_dlls.sh /path/to/mpv/build +set -e +export PATH=/mingw64/bin:/usr/bin:$PATH +cd "${1:?usage: bundle_dlls.sh }" + +collect() { + ldd "$1" 2>/dev/null | awk '{print $3}' | grep '^/mingw64/' || true +} + +declare -A seen +queue=("mpv.exe") +while [ ${#queue[@]} -gt 0 ]; do + cur="${queue[0]}" + queue=("${queue[@]:1}") + for dll in $(collect "$cur"); do + base=$(basename "$dll") + if [ -n "${seen[$base]}" ]; then continue; fi + seen[$base]=1 + queue+=("$dll") + done +done + +echo "DLLs to copy: ${#seen[@]}" +for name in "${!seen[@]}"; do + cp -f "/mingw64/bin/$name" . +done +ls -1 *.dll | wc -l diff --git a/src/container_scan.cpp b/src/container_scan.cpp new file mode 100644 index 0000000..43936bc --- /dev/null +++ b/src/container_scan.cpp @@ -0,0 +1,544 @@ +#include "container_scan.h" + +#include + +#include +#include +#include +#include + +#include "log.h" +#include "win_path.h" + +namespace joc_container { +namespace { + +// A library scan probes every container in the library, and most of them are +// declined; they also mostly share a directory, so the path would spend the log's +// byte budget repeating the same prefix once per file. The file name is what +// identifies the line. Files this component claims are logged with their full +// path by the caller. +std::string file_name_of(const std::string& path) { + const std::string::size_type slash = path.find_last_of("\\/"); + return (slash == std::string::npos) ? path : path.substr(slash + 1); +} + +// A bounded, read-only view of the file. Every accessor returns false instead of +// throwing, so a truncated or hostile file simply fails the probe. +class Window { +public: + bool open(const std::string& path) { + const std::wstring wide = joc_path::to_wide_extended(path); + handle_ = CreateFileW(wide.c_str(), GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_WRITE, + nullptr, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, nullptr); + if (handle_ == INVALID_HANDLE_VALUE) { + handle_ = nullptr; + return false; + } + LARGE_INTEGER size{}; + if (GetFileSizeEx(handle_, &size) == FALSE) return false; + size_ = static_cast(size.QuadPart); + return true; + } + + ~Window() { + if (handle_ != nullptr) CloseHandle(handle_); + } + + std::uint64_t size() const { return size_; } + + // Reads at an absolute offset; false when the range is not fully available. + bool read(std::uint64_t offset, void* destination, std::size_t bytes) const { + if (offset + bytes > size_) return false; + LARGE_INTEGER position{}; + position.QuadPart = static_cast(offset); + if (SetFilePointerEx(handle_, position, nullptr, FILE_BEGIN) == FALSE) return false; + std::size_t done = 0; + auto* target = static_cast(destination); + while (done < bytes) { + const DWORD chunk = static_cast( + (bytes - done) > 0x10000u ? 0x10000u : (bytes - done)); + DWORD got = 0; + if (ReadFile(handle_, target + done, chunk, &got, nullptr) == FALSE || got == 0) { + return false; + } + done += got; + } + return true; + } + + bool load(std::uint64_t offset, std::size_t bytes, std::vector* out) const { + out->assign(bytes, 0); + return bytes == 0 || read(offset, out->data(), bytes); + } + +private: + HANDLE handle_ = nullptr; + std::uint64_t size_ = 0; +}; + +// Set JOC_SCAN_TRACE=1 to have the walk printed: the practical way to see where a +// container's structure stops matching what the probe expects. +bool trace_enabled() { + static const bool enabled = [] { + return GetEnvironmentVariableA("JOC_SCAN_TRACE", nullptr, 0) != 0; + }(); + return enabled; +} + +void trace(const char* format, ...) { + if (!trace_enabled()) return; + va_list arguments; + va_start(arguments, format); + std::vfprintf(stdout, format, arguments); + va_end(arguments); + std::fflush(stdout); +} + +std::uint32_t be32(const std::uint8_t* p) { + return (static_cast(p[0]) << 24) | (static_cast(p[1]) << 16) | + (static_cast(p[2]) << 8) | static_cast(p[3]); +} + +std::string fourcc(const std::uint8_t* p) { return std::string(reinterpret_cast(p), 4); } + +bool is_audio_sample_entry(const std::string& format) { + // E-AC-3 is "ec-3"; "ac-3" is plain Dolby Digital and is *not* ours. + return format == "ec-3" || format == "ec3 " || format == "EAC3"; +} + +bool is_ac3_sample_entry(const std::string& format) { return format == "ac-3" || format == "ac3 "; } + +// --- MP4 / ISO base media ------------------------------------------------- + +// Walks the boxes inside [begin, end) and hands each to the visitor. +template +bool walk_boxes(const Window& file, std::uint64_t begin, std::uint64_t end, + std::size_t depth, Fn visitor) { + std::uint64_t offset = begin; + std::uint8_t header[8]; + while (offset + 8 <= end) { + if (!file.read(offset, header, sizeof(header))) return false; + std::uint64_t size = be32(header); + const std::string type = fourcc(header + 4); + std::uint64_t payload = offset + 8; + if (size == 1) { + std::uint8_t extended[8]; + if (!file.read(offset + 8, extended, sizeof(extended))) return false; + size = (static_cast(be32(extended)) << 32) | be32(extended + 4); + payload = offset + 16; + } else if (size == 0) { + size = end - offset; // "to the end of the file" + } + trace("%*sbox %s size=%llu\n", static_cast(depth) * 2, "", type.c_str(), static_cast(size)); + if (size < 8 || offset + size > end) return false; + if (!visitor(type, payload, offset + size, depth)) return false; + offset += size; + } + return true; +} + +// One trak: is it an audio track, and which sample entry does it use? +struct TrackInfo { + bool audio = false; + std::string format; +}; + +bool scan_stbl(const Window& file, std::uint64_t begin, std::uint64_t end, TrackInfo* info) { + return walk_boxes(file, begin, end, 0, [&](const std::string& type, std::uint64_t payload, + std::uint64_t box_end, std::size_t) { + (void)box_end; + if (type == "stsd") { + std::uint8_t head[16]; + if (file.read(payload, head, sizeof(head))) { + // version+flags(4) entry_count(4), then the first sample entry: + // size(4) format(4). + info->format = fourcc(head + 12); + trace("%*sstsd format=%s\n", 8, "", info->format.c_str()); + } + return false; // one sample entry is all the probe needs + } + return true; + }); +} + +// minf -> stbl -> stsd +bool scan_minf(const Window& file, std::uint64_t begin, std::uint64_t end, TrackInfo* info) { + return walk_boxes(file, begin, end, 0, [&](const std::string& type, std::uint64_t payload, + std::uint64_t box_end, std::size_t) { + if (type == "stbl") scan_stbl(file, payload, box_end, info); + return true; + }); +} + +// mdia: the track handler says whether this is audio, minf leads to the sample entry. +bool scan_mdia(const Window& file, std::uint64_t begin, std::uint64_t end, TrackInfo* info) { + return walk_boxes(file, begin, end, 0, [&](const std::string& type, std::uint64_t payload, + std::uint64_t box_end, std::size_t) { + if (type == "hdlr") { + std::uint8_t head[12]; + if (file.read(payload, head, sizeof(head))) { + info->audio = fourcc(head + 8) == "soun"; + trace("%*shdlr handler=%s audio=%d\n", 6, "", fourcc(head + 8).c_str(), + info->audio ? 1 : 0); + } + } else if (type == "minf") { + scan_minf(file, payload, box_end, info); + } + return true; + }); +} + +// trak -> mdia +bool scan_trak(const Window& file, std::uint64_t begin, std::uint64_t end, TrackInfo* info) { + return walk_boxes(file, begin, end, 0, [&](const std::string& type, std::uint64_t payload, + std::uint64_t box_end, std::size_t) { + if (type == "mdia") scan_mdia(file, payload, box_end, info); + return true; + }); +} +Result scan_mp4(const Window& file, std::size_t max_bytes) { + Result result; + result.kind = Kind::kMp4; + + // moov is usually at the start for streamed files and at the end otherwise. The + // walk reads box headers where they lie and steps over mdat in one go, so the + // whole file is walked from the top: a fixed prefix window cannot reach a moov + // that is larger than the window, which is what an MP4 with its cover art stored + // as a video track produces (a 4.9 MB moov against a 4 MiB window). The tail + // range stays as a fallback for a file whose leading boxes do not parse. + struct Range { + std::uint64_t begin; + std::uint64_t end; + }; + std::vector ranges{{0, file.size()}}; + if (file.size() > max_bytes) { + ranges.push_back({file.size() - max_bytes, file.size()}); + } + // An oversized moov is a file this probe cannot describe, and walking it would be + // unbounded work; it is reported instead of entered. + constexpr std::uint64_t kMaxMoovBytes = 64ull * 1024ull * 1024ull; + bool oversized_moov = false; + + unsigned audio_seen = 0; + bool found_any_audio = false; + std::string first_audio_format; + for (const Range& range : ranges) { + walk_boxes(file, range.begin, range.end, 0, + [&](const std::string& type, std::uint64_t payload, std::uint64_t box_end, + std::size_t) { + if (type != "moov") return true; + if (box_end - payload > kMaxMoovBytes) { + oversized_moov = true; + return true; + } + walk_boxes(file, payload, box_end, 1, + [&](const std::string& inner, std::uint64_t inner_payload, + std::uint64_t inner_end, std::size_t) { + if (inner == "mvhd") { + // version(1) flags(3) then either + // creation/modification/timescale/duration (32-bit) + // or the 64-bit variant. + std::uint8_t header[32]; + if (file.read(inner_payload, header, sizeof(header))) { + const bool wide = header[0] == 1; + const std::uint32_t timescale = + wide ? be32(header + 20) : be32(header + 12); + const std::uint64_t duration = + wide ? ((static_cast( + be32(header + 24)) + << 32) | + be32(header + 28)) + : be32(header + 16); + if (timescale != 0) { + result.duration_seconds = + static_cast(duration) / + static_cast(timescale); + } + } + return true; + } + if (inner != "trak") return true; + TrackInfo info; + scan_trak(file, inner_payload, inner_end, &info); + if (!info.audio) return true; + if (!found_any_audio) { + found_any_audio = true; + first_audio_format = info.format; + } + if (is_audio_sample_entry(info.format)) { + result.eac3 = true; + result.audio_index = audio_seen; + result.codec = info.format; + } else if (is_ac3_sample_entry(info.format)) { + result.codec = info.format; + } + ++audio_seen; + return !result.eac3; // stop once found + }); + return !result.eac3; + }); + if (result.eac3) break; + } + + if (result.eac3) { + result.detail = "mp4: E-AC-3 audio track " + std::to_string(result.audio_index); + } else if (found_any_audio) { + result.detail = "mp4: first audio track is " + + (first_audio_format.empty() ? std::string("unknown") + : first_audio_format); + } else if (oversized_moov) { + result.detail = "mp4: moov is larger than the scan limit"; + } else { + result.detail = "mp4: no audio track found in the scanned window"; + } + return result; +} + +// --- Matroska / WebM ------------------------------------------------------ + +struct EbmlReader { + const std::uint8_t* data = nullptr; + std::size_t size = 0; + std::size_t position = 0; + + bool at_end() const { return position >= size; } + + // Element IDs keep their leading bits; sizes drop the marker bit. + bool read_id(std::uint64_t* id) { + if (at_end()) return false; + const std::uint8_t first = data[position]; + int length = 1; + for (int bit = 0x80; bit != 0; bit >>= 1, ++length) { + if ((first & bit) != 0) break; + } + if (length > 4 || position + static_cast(length) > size) return false; + std::uint64_t value = 0; + for (int i = 0; i < length; ++i) value = (value << 8) | data[position + i]; + position += static_cast(length); + *id = value; + return true; + } + + bool read_size(std::uint64_t* value, bool* unknown) { + *unknown = false; + if (at_end()) return false; + const std::uint8_t first = data[position]; + int length = 1; + for (int bit = 0x80; bit != 0; bit >>= 1, ++length) { + if ((first & bit) != 0) break; + } + if (length > 8 || position + static_cast(length) > size) return false; + std::uint64_t result = first & (0xFFu >> length); + bool all_ones = (first & (0xFFu >> length)) == (0xFFu >> length); + for (int i = 1; i < length; ++i) { + const std::uint8_t byte = data[position + i]; + all_ones = all_ones && byte == 0xFFu; + result = (result << 8) | byte; + } + position += static_cast(length); + *unknown = all_ones; + *value = result; + return true; + } +}; + +Result scan_matroska(const Window& file, std::size_t max_bytes) { + Result result; + result.kind = Kind::kMatroska; + + std::vector data; + if (!file.load(0, static_cast( + (std::min)(file.size(), max_bytes)), + &data)) { + result.detail = "matroska: cannot read the header"; + return result; + } + + unsigned audio_seen = 0; + std::string first_audio_codec; + bool saw_tracks = false; + bool found = false; + double timestamp_scale_ns = 1000000.0; // Matroska default: 1 ms per tick + double duration_ticks = 0.0; + + // Only the two levels that matter are walked: Tracks, then TrackEntry. + auto walk = [&](std::size_t begin, std::size_t end, int depth, + auto&& self) -> void { + EbmlReader reader{data.data(), end, begin}; + while (!reader.at_end() && !found) { + const std::size_t element_start = reader.position; + std::uint64_t id = 0; + std::uint64_t size = 0; + bool unknown = false; + if (!reader.read_id(&id) || !reader.read_size(&size, &unknown)) break; + std::size_t payload = reader.position; + std::size_t payload_end = + unknown ? end : (std::min)(end, payload + static_cast(size)); + if (payload_end < payload) break; + + switch (id) { + case 0x1654AE6Bu: // Tracks + saw_tracks = true; + self(payload, payload_end, depth + 1, self); + break; + case 0x1549A966u: { // Info: carries the segment duration + EbmlReader inner{data.data(), payload_end, payload}; + while (!inner.at_end()) { + std::uint64_t child_id = 0; + std::uint64_t child_size = 0; + bool child_unknown = false; + if (!inner.read_id(&child_id) || + !inner.read_size(&child_size, &child_unknown)) { + break; + } + const std::size_t child_payload = inner.position; + const std::size_t child_end = + child_unknown ? payload_end + : (std::min)( + payload_end, + child_payload + static_cast(child_size)); + // TimestampScale (ns per tick, default 1 ms) and Duration (ticks). + if (child_id == 0x2AD7B1u && child_size >= 1 && child_size <= 8) { + std::uint64_t scale = 0; + for (std::size_t i = 0; i < child_size; ++i) { + scale = (scale << 8) | data[child_payload + i]; + } + if (scale != 0) timestamp_scale_ns = scale; + } else if (child_id == 0x4489u && (child_size == 4 || child_size == 8)) { + // Duration is a big-endian float: 4 or 8 bytes, both occur. + const std::uint8_t* field = data.data() + child_payload; + if (child_size == 4) { + const std::uint32_t bits = be32(field); + float value = 0.0f; + std::memcpy(&value, &bits, sizeof(value)); + duration_ticks = static_cast(value); + } else { + const std::uint64_t bits = + (static_cast(be32(field)) << 32) | be32(field + 4); + double value = 0.0; + std::memcpy(&value, &bits, sizeof(value)); + duration_ticks = value; + } + } + inner.position = child_end; + } + break; + } + case 0xAEu: { // TrackEntry + // Read this track's type and codec. + std::uint64_t track_type = 0; + std::string codec; + EbmlReader inner{data.data(), payload_end, payload}; + while (!inner.at_end()) { + std::uint64_t child_id = 0; + std::uint64_t child_size = 0; + bool child_unknown = false; + if (!inner.read_id(&child_id) || + !inner.read_size(&child_size, &child_unknown)) { + break; + } + const std::size_t child_payload = inner.position; + const std::size_t child_end = + child_unknown ? payload_end + : (std::min)( + payload_end, + child_payload + static_cast(child_size)); + if (child_id == 0x83u && child_size >= 1) { // TrackType + track_type = data[child_payload]; + } else if (child_id == 0x86u) { // CodecID + codec.assign(reinterpret_cast(data.data() + child_payload), + child_end - child_payload); + } + inner.position = child_end; + } + if (track_type == 2u) { // audio + if (first_audio_codec.empty()) first_audio_codec = codec; + if (codec == "A_EAC3") { + result.eac3 = true; + result.audio_index = audio_seen; + result.codec = codec; + found = true; + } + ++audio_seen; + } + break; + } + case 0x18538067u: // Segment: descend, the size may be unknown + self(payload, payload_end, depth + 1, self); + break; + default: + break; + } + if (found) break; + reader.position = payload_end; + if (payload_end == element_start) break; // no progress: stop + } + }; + walk(0, data.size(), 0, walk); + + if (duration_ticks > 0.0 && timestamp_scale_ns > 0.0) { + result.duration_seconds = duration_ticks * timestamp_scale_ns / 1.0e9; + } + if (result.eac3) { + result.detail = "matroska: E-AC-3 audio track " + std::to_string(result.audio_index); + } else if (saw_tracks) { + result.detail = "matroska: first audio track is " + + (first_audio_codec.empty() ? std::string("unknown") : first_audio_codec); + } else { + result.detail = "matroska: no track list in the scanned window"; + } + return result; +} + +} // namespace + +const char* kind_name(Kind kind) { + switch (kind) { + case Kind::kMp4: return "mp4"; + case Kind::kMatroska: return "matroska"; + default: return "none"; + } +} + +bool is_container_extension(const char* extension) { + if (extension == nullptr) return false; + static const char* const kExtensions[] = {"mp4", "m4a", "m4b", "m4p", "m4r", + "mov", "mkv", "mka", "webm"}; + for (const char* candidate : kExtensions) { + if (_stricmp(extension, candidate) == 0) return true; + } + return false; +} + +Result scan(const std::string& path, std::size_t max_bytes) { + Result result; + Window file; + if (!file.open(path)) { + result.detail = "cannot open the file"; + return result; + } + if (file.size() < 16) { + result.detail = "file too small to be a container"; + return result; + } + + std::uint8_t head[16]; + if (!file.read(0, head, sizeof(head))) { + result.detail = "cannot read the file header"; + return result; + } + // Matroska starts with the EBML header element (0x1A45DFA3); ISO base media + // starts with a box whose type is at offset 4 ("ftyp" for a normal file). + if (head[0] == 0x1A && head[1] == 0x45 && head[2] == 0xDF && head[3] == 0xA3) { + result = scan_matroska(file, max_bytes); + } else { + result = scan_mp4(file, max_bytes); + } + joc_log::line("container: %s -> %s (eac3=%d audio#%u codec=%s)", file_name_of(path).c_str(), + result.detail.c_str(), result.eac3 ? 1 : 0, result.audio_index, + result.codec.empty() ? "-" : result.codec.c_str()); + return result; +} + +} // namespace joc_container \ No newline at end of file diff --git a/src/container_scan.h b/src/container_scan.h new file mode 100644 index 0000000..df73dfd --- /dev/null +++ b/src/container_scan.h @@ -0,0 +1,47 @@ +// Cheap structural probe of container files, to answer one question: does this +// file hold an E-AC-3 audio track, and if so which one? +// +// It exists so that a Media Library scan does not pay for an ffmpeg launch on +// every MP4 in the collection. The probe reads a bounded window of the file and +// walks only the headers it needs: +// +// MP4 / MOV top-level boxes -> moov -> trak -> hdlr(mdia) + stsd sample entry. +// moov may sit at the end (no faststart), so the tail is checked too. +// Matroska EBML header -> Segment -> Tracks -> TrackEntry -> CodecID. +// +// The E-AC-3 bitstream itself is never demuxed here: ffmpeg extracts it when the +// file is actually decoded, which keeps this file small and lets every container +// ffmpeg understands work without a demuxer of our own. +#pragma once + +#include +#include + +namespace joc_container { + +enum class Kind { + kNone, + kMp4, + kMatroska, +}; + +const char* kind_name(Kind kind); + +struct Result { + Kind kind = Kind::kNone; + bool eac3 = false; // an E-AC-3 audio track is present + unsigned audio_index = 0; // which audio track it is, 0-based + double duration_seconds = 0.0; // from the container header, 0 when not stated + std::string codec; // codec identifier found, for the log + std::string detail; +}; + +// True when the extension belongs to a container this component looks inside. +bool is_container_extension(const char* extension); + +// Reads at most max_bytes of header (plus the same amount at the end for MP4) and +// reports what it found. Missing files, empty files and unknown containers come +// back as Kind::kNone with a detail string. +Result scan(const std::string& path, std::size_t max_bytes = 4u * 1024u * 1024u); + +} // namespace joc_container diff --git a/src/cplugin_main.cpp b/src/cplugin_main.cpp new file mode 100644 index 0000000..40ed5f5 --- /dev/null +++ b/src/cplugin_main.cpp @@ -0,0 +1,570 @@ +// mpv C plugin: E-AC-3 JOC (Dolby Atmos) playback. +// +// mpv decodes the file's video and its E-AC-3 bed normally; this plugin adds a +// second audio track that carries the object-audio rendering. The rendering +// itself is the same kernel, the same engine and the same settings as the +// upstream frontends, so the delivered samples match them bit for bit. +// +// The track is served over a loopback HTTP range endpoint backed by the +// renderer: mpv reads it as an ordinary seekable WAV, which is what lets its +// demuxer, cache, A/V sync, WASAPI output and seeking all keep working. + +#include +#include + +// Every mpv_* call goes through the host's exported symbol table: a cplugin +// must not link against libmpv. +#ifndef MPV_CPLUGIN_DYNAMIC_SYM +#define MPV_CPLUGIN_DYNAMIC_SYM +#endif +#include + +#include +#include +#include +#include +#include +#include +#include + +#include "container_scan.h" +#include "joc_decode.h" +#include "log.h" +#include "win_path.h" +#include "plugin/audio_source.h" +#include "plugin/config.h" +#include "plugin/http_server.h" +#include "plugin/wav.h" + +namespace { + +constexpr const char* kResource = "/joc.wav"; + +std::string plugin_directory() { return joc_decode::component_directory(); } + +bool file_exists(const std::string& path) { + std::wstring wide; + const int needed = MultiByteToWideChar(CP_UTF8, 0, path.c_str(), -1, nullptr, 0); + if (needed <= 1) return false; + wide.resize(static_cast(needed)); + MultiByteToWideChar(CP_UTF8, 0, path.c_str(), -1, wide.data(), needed); + const DWORD attributes = GetFileAttributesW(wide.c_str()); + return attributes != INVALID_FILE_ATTRIBUTES && (attributes & FILE_ATTRIBUTE_DIRECTORY) == 0; +} + +// The default HRTF lives next to the plugin, or one level up when the plugin +// sits in \scripts and the data in itself. +std::string default_hrtf_file(const joc_mpv::Config& config) { + const char* name = (config.hrtf_source == 0) ? "binaural.sofa" + : "binaural.personalized_headphone"; + const std::string directory = plugin_directory(); + const std::string candidates[] = {directory + "\\HRTF\\" + name, + directory + "\\..\\HRTF\\" + name}; + for (const std::string& candidate : candidates) { + if (file_exists(candidate)) return candidate; + } + return {}; +} + +// Sent as a node array rather than a command string: an error message carries +// backslashes and non-ASCII text, which the command parser would mangle. +void osd(mpv_handle* mpv, const std::string& text) { + mpv_node values[3]; + values[0].format = MPV_FORMAT_STRING; + values[0].u.string = const_cast("show-text"); + values[1].format = MPV_FORMAT_STRING; + values[1].u.string = const_cast(text.c_str()); + values[2].format = MPV_FORMAT_STRING; + values[2].u.string = const_cast("3000"); + mpv_node_list list{}; + list.num = 3; + list.values = values; + mpv_node command{}; + command.format = MPV_FORMAT_NODE_ARRAY; + command.u.list = &list; + mpv_command_node(mpv, &command, nullptr); +} + +// Byte offset of the first syncframe. A bare stream may start with an ID3v2 +// tag, which the renderer refuses to parse as audio. +std::uint64_t leading_tag_bytes(const std::string& path) { + FILE* file = _wfopen(joc_path::to_wide_extended(path).c_str(), L"rb"); + if (file == nullptr) return 0; + unsigned char header[10] = {}; + const std::size_t got = std::fread(header, 1, sizeof(header), file); + std::fclose(file); + if (got != sizeof(header) || std::memcmp(header, "ID3", 3) != 0) return 0; + auto synchsafe = [](unsigned char a, unsigned char b, unsigned char c, unsigned char d) { + return (static_cast(a & 0x7F) << 21) | + (static_cast(b & 0x7F) << 14) | + (static_cast(c & 0x7F) << 7) | + static_cast(d & 0x7F); + }; + const std::uint64_t size = synchsafe(header[6], header[7], header[8], header[9]); + // The footer flag (0x10) adds another 10 bytes after the tag body. + const std::uint64_t footer = (header[5] & 0x10) != 0 ? 10u : 0u; + return 10u + size + footer; +} + +std::string format_channels(unsigned channels, const std::string& layout, int output) { + if (output == 0) return "binaural 2ch"; + return layout + " " + std::to_string(channels) + "ch"; +} + +// The WAV the plugin serves: header plus the rendered data chunk. +struct Stream { + std::shared_ptr source; + std::string header; + std::uint64_t total_bytes = 0; + std::size_t write_bytes = 65536; + bool verbose = false; + // Only the newest request may read from the renderer: a request that mpv + // replaces (a seek closes the old stream and opens a new one) has to stop + // instead of pulling the renderer back to its own position. + std::atomic generation{0}; +}; + +// Streams the requested part of the file until the client closes the +// connection or the audio ends. mpv seeks by reopening the URL with a new +// Range, which becomes a renderer seek. +void serve_request(const std::shared_ptr& stream, const joc_mpv::HttpRequest& request, + joc_mpv::HttpResponse* response) { + if (request.method != "GET") { + response->status = 400; + return; + } + if (request.target.compare(0, std::strlen(kResource), kResource) != 0) { + response->status = 404; + return; + } + const std::uint64_t header_size = stream->header.size(); + const std::uint64_t total = stream->total_bytes; + const std::uint64_t start = request.has_range ? request.range_start : 0; + if (start >= total) { + response->status = 416; + response->headers = "Content-Range: bytes */" + std::to_string(total) + "\r\n"; + return; + } + response->status = request.has_range ? 206 : 200; + response->headers = "Content-Type: audio/wav\r\n"; + response->headers += "Accept-Ranges: bytes\r\n"; + if (request.has_range) { + response->headers += "Content-Range: bytes " + std::to_string(start) + "-" + + std::to_string(total - 1) + "/" + std::to_string(total) + "\r\n"; + } + if (stream->verbose) { + joc_log::line("http: %s %s from %llu of %llu", request.method.c_str(), + request.target.c_str(), static_cast(start), + static_cast(total)); + } + const unsigned generation = stream->generation.fetch_add(1) + 1; + const std::uint64_t last = + (request.has_range && request.has_range_end) + ? std::min(request.range_end, total - 1) + : total - 1; + response->stream = [stream, start, last, header_size, total, generation]( + joc_mpv::ResponseWriter& writer) { + const unsigned frame_bytes = stream->source->bytes_per_frame(); + std::vector buffer(stream->write_bytes); + std::uint64_t offset = start; + // The WAV header is one chunk of its own: from the first data byte on, + // every offset is a whole number of frames, so the renderer never has to + // reposition just because a write did not end on a frame boundary. + if (offset < header_size) { + const std::size_t take = static_cast( + std::min(header_size - offset, last + 1 - offset)); + if (!writer.write(stream->header.data() + offset, take)) return; + offset += take; + } + while (offset <= last) { + if (stream->generation.load() != generation) break; + std::size_t want = static_cast( + std::min(buffer.size(), last + 1 - offset)); + want -= want % frame_bytes; + if (want == 0) break; + std::string error; + const std::size_t got = + stream->source->read(offset - header_size, buffer.data(), want, &error); + if (got == 0) { + if (stream->verbose) { + joc_log::line("http: stream ended at %llu: %s", + static_cast(offset), error.c_str()); + } + break; + } + if (!writer.write(buffer.data(), got)) break; + offset += got; + } + }; +} + +struct Plugin { + mpv_handle* mpv = nullptr; + joc_mpv::Config config; + std::unique_ptr server; + std::shared_ptr stream; + std::string current_path; // the file a stream was prepared for + std::string url; + // The last file a probe answered for, so a rejected input is not probed a + // second time at file-loaded. + std::string probed_path; + bool probed_joc = false; + std::string config_dir; + // The file's own audio is muted (when the configuration asks for it) from + // the first sample until the rendered track takes over, so the opening of a + // JOC file is never the plain bed. The player's own mute state is restored. + bool muted_by_us = false; + bool saved_mute = false; + + void stop_stream() { + if (stream) stream->generation.fetch_add(1); + if (server) server->stop(); + if (stream && stream->source) stream->source->close(); + stream.reset(); + server.reset(); + current_path.clear(); + url.clear(); + } + + bool muted_state() { + int flag = 0; + if (mpv_get_property(mpv, "mute", MPV_FORMAT_FLAG, &flag) < 0) return false; + return flag != 0; + } + + void set_muted(bool muted) { + int flag = muted ? 1 : 0; + mpv_set_property(mpv, "mute", MPV_FORMAT_FLAG, &flag); + } + + void suppress_bed() { + if (!config.mute_until_ready || muted_by_us) return; + saved_mute = muted_state(); + if (saved_mute) return; // the player is already silent; nothing to restore + set_muted(true); + muted_by_us = true; + } + + void restore_bed() { + if (!muted_by_us) return; + set_muted(saved_mute); + muted_by_us = false; + } + + // Only inputs that can carry E-AC-3 JOC are worth silencing before the + // probe answers; anything else would lose its first moments to a mute. + static bool candidate(const std::string& path) { + const std::size_t dot = path.find_last_of('.'); + if (dot == std::string::npos) return false; + std::string extension = path.substr(dot + 1); + for (char& ch : extension) { + if (ch >= 'A' && ch <= 'Z') ch = static_cast(ch - 'A' + 'a'); + } + static const char* const kExtensions[] = {"eac3", "ec3", "ac3", "mp4", "m4a", "m4b", + "mov", "mkv", "mka", "webm"}; + for (const char* known : kExtensions) { + if (extension == known) return true; + } + return false; + } + + bool probe(const std::string& path, joc_decode::Settings* settings, double* duration) { + const std::uint64_t tag_bytes = leading_tag_bytes(path); + const joc_decode::FileProbe bare = joc_decode::probe_file(path, 0, tag_bytes); + if (bare.readable && bare.joc) { + settings->input_kind = joc_decode::InputKind::kBare; + settings->stream_start_bytes = tag_bytes; + *duration = bare.duration_seconds; + joc_log::line("probe: %s is a JOC stream (%llu frames, %.3f s)", path.c_str(), + static_cast(bare.frames), *duration); + return true; + } + const joc_container::Result container = joc_container::scan(path); + if (container.kind == joc_container::Kind::kNone || !container.eac3) { + joc_log::line("probe: %s is not an E-AC-3 JOC input (%s)", path.c_str(), + container.detail.c_str()); + return false; + } + bool verdict = false; + std::string detail; + if (!joc_decode::probe_container_joc(config.ffmpeg, path, container.audio_index, &verdict, + &detail) || + !verdict) { + joc_log::line("probe: container %s track %u is not JOC (%s)", path.c_str(), + container.audio_index, detail.c_str()); + return false; + } + settings->input_kind = joc_decode::InputKind::kContainer; + settings->audio_index = container.audio_index; + *duration = container.duration_seconds; + joc_log::line("probe: %s carries JOC in audio track %u (%.3f s)", path.c_str(), + container.audio_index, *duration); + return true; + } + + // Starts the renderer and its endpoint for a file, without touching the + // player yet: at start-file the entry is not loaded, so audio-add could only + // be applied to the previous one. Returns true when a stream is ready. + bool prepare(const std::string& path) { + stop_stream(); + probed_path = path; + probed_joc = false; + if (!config.enabled) return false; + + joc_decode::Settings settings; + settings.output = (config.output == 0) ? joc_decode::Output::kBinaural + : joc_decode::Output::kSpeaker; + settings.speaker_layout = config.layout; + settings.hrtf_source = (config.hrtf_source == 0) ? joc_decode::HrtfSource::kSofa + : joc_decode::HrtfSource::kRosella; + settings.hrtf_file = config.hrtf_file; + if (settings.hrtf_file.empty() && settings.output == joc_decode::Output::kBinaural) { + settings.hrtf_file = default_hrtf_file(config); + } + settings.binaural_mode = static_cast(config.binaural_mode); + settings.gain_db = config.gain_db; + settings.tail_seconds = config.tail_seconds; + settings.force_int24 = config.force_int24; + settings.object_delay_samples = config.object_delay_samples; + settings.native_threads = config.native_threads; + settings.ffmpeg_path = config.ffmpeg; + settings.core_path = config.core_dll; + // The compiled SOFA field is the dominant part of the startup cost; + // keeping it on disk makes every later file (and every seek restart-free + // start) skip that work. + if (config.verbose) { + joc_log::line("config: hrtf-cache=%s dir=%s", config.hrtf_cache.c_str(), + config.hrtf_cache_dir.c_str()); + } + if (config.hrtf_cache == "none") { + settings.hrtf_cache_policy = 0; + } else if (config.hrtf_cache == "memory") { + settings.hrtf_cache_policy = 1; + } else { + // disk and auto: the config directory is the natural place for a + // cache; without one the renderer compiles in memory as before. + std::string directory = config.hrtf_cache_dir; + if (directory.empty() && !config_dir.empty()) { + directory = config_dir + "\\joc-hrtf-cache"; + } + if (!directory.empty()) { + settings.hrtf_cache_policy = 2; + settings.hrtf_cache_dir = directory; + } else { + settings.hrtf_cache_policy = 1; + } + } + settings.pipeline_delay_samples = joc_decode::kJocSeekPipelineDelaySamples; + settings.seek_preroll_frames = joc_decode::kJocSeekPrerollFrames; + + double duration = 0.0; + if (!probe(path, &settings, &duration)) return false; + + // A container header may not state a duration; the player knows it. + if (!(duration > 0.0)) { + double from_player = 0.0; + if (mpv_get_property(mpv, "duration", MPV_FORMAT_DOUBLE, &from_player) >= 0) { + duration = from_player; + } + } + if (!(duration > 0.0)) { + joc_log::line("start: no duration for %s, leaving the input to mpv", path.c_str()); + osd(mpv, "JOC: unknown duration, plugin skipped"); + return false; + } + settings.length_seconds = duration; + + auto source = std::make_shared(); + std::string error; + if (!source->open(path, settings, duration, &error)) { + // A disk cache that cannot be used must not cost playback: retry the + // way this worked before the cache existed. + if (settings.hrtf_cache_policy == 2) { + joc_log::line("prepare: disk HRTF cache unusable (%s); retrying in memory", + error.c_str()); + settings.hrtf_cache_policy = 1; + settings.hrtf_cache_dir.clear(); + error.clear(); + } + if (!source->open(path, settings, duration, &error)) { + joc_log::line("start: renderer failed for %s: %s", path.c_str(), error.c_str()); + osd(mpv, "JOC: " + error); + return false; + } + } + + auto created = std::make_shared(); + created->source = source; + const std::string mask_layout = (config.output == 0) ? "2.0" : config.layout; + created->header = joc_mpv::wav_header( + source->channels(), source->bits_per_sample(), + joc_mpv::channel_mask(mask_layout, source->channels()), source->data_bytes()); + created->total_bytes = created->header.size() + source->data_bytes(); + const double per_write = config.chunk_seconds * 48000.0 * + static_cast(source->bytes_per_frame()); + created->write_bytes = static_cast( + std::min(4.0 * 1024.0 * 1024.0, std::max(16.0 * 1024.0, per_write))); + created->verbose = config.verbose; + + auto http = std::make_unique(); + unsigned short port = 0; + const std::shared_ptr captured = created; + if (!http->start( + [captured](const joc_mpv::HttpRequest& request, joc_mpv::HttpResponse* response) { + serve_request(captured, request, response); + }, + &port, &error)) { + joc_log::line("start: %s", error.c_str()); + osd(mpv, "JOC: " + error); + source->close(); + return false; + } + + stream = created; + server = std::move(http); + current_path = path; + url = "http://127.0.0.1:" + std::to_string(port) + kResource; + probed_joc = true; + joc_log::line("prepare: %s -> %s (%s, %s)", path.c_str(), url.c_str(), + format_channels(source->channels(), config.layout, config.output).c_str(), + config.ffmpeg.c_str()); + return true; + } + + // Adds the prepared stream as a selected audio track and lets the player's + // own audio come back. + void attach() { + if (!stream || current_path.empty()) return; + if (!config.attach) { + joc_log::line("attach: disabled (joc-attach=no); serving %s", url.c_str()); + restore_bed(); + return; + } + const std::string title = + "JOC " + (config.output == 0 ? std::string("binaural") : config.layout); + const char* arguments[] = {"audio-add", url.c_str(), "select", title.c_str(), nullptr}; + const int result = mpv_command(mpv, arguments); + if (result < 0) { + joc_log::line("attach: audio-add failed: %s", mpv_error_string(result)); + osd(mpv, std::string("JOC: audio-add failed: ") + mpv_error_string(result)); + stop_stream(); + restore_bed(); + return; + } + restore_bed(); + const std::string summary = + "JOC: " + format_channels(stream->source->channels(), config.layout, config.output) + + (config.force_int24 ? " int24" : " float32"); + joc_log::line("attach: %s (%s)", current_path.c_str(), summary.c_str()); + osd(mpv, summary); + } +}; + +std::string read_string_property(mpv_handle* mpv, const char* name) { + char* value = mpv_get_property_string(mpv, name); + if (value == nullptr) return {}; + std::string text(value); + mpv_free(value); + return text; +} + +std::wstring to_wide(const std::string& text) { + if (text.empty()) return {}; + const int needed = MultiByteToWideChar(CP_UTF8, 0, text.c_str(), -1, nullptr, 0); + if (needed <= 1) return {}; + std::wstring wide(static_cast(needed), L'\0'); + MultiByteToWideChar(CP_UTF8, 0, text.c_str(), -1, wide.data(), needed); + wide.resize(static_cast(needed - 1)); + return wide; +} + +// Diagnostics must not land in the directory mpv scans for scripts: every file +// there is offered to the script loader. The player's config directory is the +// natural place; one level above the plugin is the fallback. +void configure_log_directory(mpv_handle* mpv, const joc_mpv::Config& config) { + std::string path = config.log_path; + if (path.empty()) { + std::string directory = read_string_property(mpv, "options/config-dir"); + if (directory.empty()) directory = plugin_directory() + "\\.."; + path = directory + "\\joc_decoder.log"; + } + const std::wstring wide = to_wide(path); + if (!wide.empty()) SetEnvironmentVariableW(L"JOC_LOG", wide.c_str()); +} + +void configure_output(mpv_handle* mpv, const joc_mpv::Config& config) { + if (config.wasapi == "yes") { + const int result = mpv_set_property_string(mpv, "ao", "wasapi"); + joc_log::line("output: ao=wasapi -> %s", result < 0 ? mpv_error_string(result) : "ok"); + } + if (config.exclusive) { + const int result = mpv_set_property_string(mpv, "audio-exclusive", "yes"); + joc_log::line("output: audio-exclusive=yes -> %s", + result < 0 ? mpv_error_string(result) : "ok"); + } +} + +} // namespace + +extern "C" __declspec(dllexport) int mpv_open_cplugin(mpv_handle* handle) { + Plugin plugin; + plugin.mpv = handle; + std::string warnings; + const std::string script_opts = read_string_property(handle, "options/script-opts"); + plugin.config = joc_mpv::parse_config(script_opts, &warnings); + plugin.config_dir = read_string_property(handle, "options/config-dir"); + configure_log_directory(handle, plugin.config); + if (!warnings.empty()) joc_log::line("config: %s", warnings.c_str()); + + joc_log::line("plugin: joc_mpv loaded (libmpv %lu, dir %s)", + static_cast(mpv_client_api_version()), + plugin_directory().c_str()); + configure_output(handle, plugin.config); + + for (;;) { + mpv_event* event = mpv_wait_event(handle, -1); + if (event == nullptr) continue; + switch (event->event_id) { + case MPV_EVENT_START_FILE: { + // The renderer starts here, while mpv is still opening the file, + // and the file's own audio is silenced first so the opening + // moments are not the plain bed. + plugin.restore_bed(); + const std::string path = read_string_property(handle, "path"); + if (path.empty() || path.find("://") != std::string::npos) break; + if (Plugin::candidate(path)) plugin.suppress_bed(); + if (!plugin.prepare(path)) plugin.restore_bed(); + break; + } + case MPV_EVENT_FILE_LOADED: { + const std::string path = read_string_property(handle, "path"); + if (path.empty() || path.find("://") != std::string::npos) break; + if (plugin.current_path != path) { + // No start-file notification (a reload, for instance), or a + // file the probe rejected there. + if (plugin.probed_path == path && !plugin.probed_joc) { + plugin.restore_bed(); + break; + } + if (!plugin.prepare(path)) { + plugin.restore_bed(); + break; + } + } + plugin.attach(); + break; + } + case MPV_EVENT_END_FILE: + plugin.stop_stream(); + plugin.restore_bed(); + break; + case MPV_EVENT_SHUTDOWN: + plugin.stop_stream(); + plugin.restore_bed(); + joc_log::line("plugin: shutting down"); + return 0; + default: + break; + } + } +} diff --git a/src/eac3_scan.cpp b/src/eac3_scan.cpp new file mode 100644 index 0000000..3997445 --- /dev/null +++ b/src/eac3_scan.cpp @@ -0,0 +1,453 @@ +#include "eac3_scan.h" + +#include + +namespace joc_eac3 { +namespace { + +constexpr std::uint16_t kEac3Syncword = 0x0B77; +constexpr std::uint16_t kEmdfSyncword = 0x5838; +constexpr std::uint8_t kIdOamd = 11; +constexpr std::uint8_t kIdJoc = 14; +constexpr std::size_t kMaxPayloads = 16; + +// MSB-first bit reader with an explicit limit, matching the core's reader +// semantics (reads past the limit fail rather than returning zeros). +class BitReader { +public: + BitReader(const std::uint8_t* data, std::size_t limit_bits, std::size_t start_bit) + : data_(data), limit_(limit_bits), position_(start_bit) {} + + std::uint32_t read(unsigned count) { + std::uint32_t value = 0; + for (unsigned i = 0; i < count; ++i) { + if (position_ >= limit_) { + failed_ = true; + return 0; + } + const unsigned byte = data_[position_ >> 3]; + value = (value << 1) | ((byte >> (7u - (position_ & 7u))) & 1u); + ++position_; + } + return value; + } + + bool skip(std::size_t count) { + if (position_ + count > limit_) { + failed_ = true; + return false; + } + position_ += count; + return true; + } + + // value, then a continuation bit; an unterminated chain is a syntax error. + bool variable_bits(unsigned width, unsigned max_groups, std::uint32_t* out) { + std::uint32_t value = 0; + for (unsigned group = 0; group < max_groups; ++group) { + value += read(width); + if (failed_) return false; + const std::uint32_t more = read(1); + if (failed_) return false; + if (more == 0u) { + if (out != nullptr) *out = value; + return true; + } + value = (value + 1u) << width; + } + failed_ = true; + return false; + } + + std::size_t position() const { return position_; } + bool failed() const { return failed_; } + void set_failed() { failed_ = true; } + +private: + const std::uint8_t* data_ = nullptr; + std::size_t limit_ = 0; + std::size_t position_ = 0; + bool failed_ = false; +}; + +struct Payload { + std::uint8_t id = 0; + std::size_t bit_offset = 0; + std::size_t size = 0; +}; + +struct Container { + std::size_t start_bit = 0; + std::size_t raw_size = 0; + std::size_t payload_count = 0; + Payload payloads[kMaxPayloads] = {}; + + bool has(std::uint8_t id) const { + for (std::size_t i = 0; i < payload_count; ++i) { + if (payloads[i].id == id) return true; + } + return false; + } +}; + +bool parse_container(const std::uint8_t* data, std::size_t size_bits, std::size_t start_bit, + Container* out) { + if (start_bit + 16u > size_bits) return false; + BitReader reader(data, size_bits, start_bit); + if (reader.read(16) != kEmdfSyncword) return false; + + const std::uint32_t length = reader.read(16); + const std::size_t body_start = reader.position(); + const std::size_t body_end = body_start + static_cast(length) * 8u; + if (reader.failed() || body_end > size_bits) return false; + + BitReader body(data, body_end, body_start); + std::uint32_t version = body.read(2); + if (body.failed()) return false; + if (version == 3u) { + std::uint32_t extra = 0; + if (!body.variable_bits(2, 8, &extra)) return false; + version += extra; + } + std::uint32_t key_id = body.read(3); + if (body.failed()) return false; + if (key_id == 7u) { + std::uint32_t extra = 0; + if (!body.variable_bits(3, 8, &extra)) return false; + key_id += extra; + } + // TS 103 420 JOC is version 0 / key_id 0; the strict check also rejects + // false 0x5838 markers that happen to sit inside audio data. + if (version != 0u || key_id != 0u) return false; + + Container container; + container.start_bit = start_bit; + bool terminated = false; + while (body.position() + 5u <= body_end) { + std::uint32_t payload_id = body.read(5); + if (body.failed()) return false; + if (payload_id == 0u) { + terminated = true; + break; + } + if (payload_id == 0x1Fu) { + std::uint32_t extra = 0; + if (!body.variable_bits(5, 8, &extra)) return false; + payload_id += extra; + } + for (std::size_t i = 0; i < container.payload_count; ++i) { + if (container.payloads[i].id == static_cast(payload_id)) return false; + } + if (container.payload_count >= kMaxPayloads) return false; + + const std::uint32_t has_sample_offset = body.read(1); + if (body.failed()) return false; + if (has_sample_offset != 0u) { + (void)body.read(12); + } + if (body.read(1) != 0u) { + std::uint32_t ignored = 0; + if (!body.variable_bits(11, 8, &ignored)) return false; + } + if (body.read(1) != 0u) { + std::uint32_t ignored = 0; + if (!body.variable_bits(2, 8, &ignored)) return false; + } + if (body.read(1) != 0u) { + if (!body.skip(8)) return false; + } + if (body.failed()) return false; + if (body.read(1) == 0u) { + bool frame_aligned = false; + if (has_sample_offset == 0u) { + frame_aligned = body.read(1) != 0u; + if (frame_aligned && !body.skip(2)) return false; + } + if ((has_sample_offset != 0u || frame_aligned) && !body.skip(7)) return false; + } + if (body.failed()) return false; + + std::uint32_t payload_size = 0; + if (!body.variable_bits(8, 8, &payload_size)) return false; + const std::size_t payload_bits = static_cast(payload_size) * 8u; + if (body.position() + payload_bits > body_end) return false; + + Payload& entry = container.payloads[container.payload_count++]; + entry.id = static_cast(payload_id); + entry.bit_offset = body.position(); + entry.size = payload_size; + if (!body.skip(payload_bits)) return false; + } + if (!terminated) return false; + container.raw_size = 4u + static_cast(length); + *out = container; + return true; +} + +// Candidate 0x5838 positions over the eight bit alignments, ascending. +void marker_offsets(const std::uint8_t* data, std::size_t size, std::size_t* out, + std::size_t capacity, std::size_t* count) { + *count = 0; + if (size < 4u) return; + for (std::size_t shift = 0; shift < 8u; ++shift) { + const std::size_t aligned_len = (shift == 0u) ? size : (size - 1u); + for (std::size_t i = 0; i + 1u < aligned_len; ++i) { + std::uint8_t first = 0; + std::uint8_t second = 0; + if (shift == 0u) { + first = data[i]; + second = data[i + 1u]; + } else { + first = static_cast( + ((static_cast(data[i]) << shift) | + (static_cast(data[i + 1u]) >> (8u - shift))) & + 0xFFu); + second = static_cast( + ((static_cast(data[i + 1u]) << shift) | + (static_cast(data[i + 2u]) >> (8u - shift))) & + 0xFFu); + } + if (first == 0x58u && second == 0x38u) { + if (*count < capacity) out[(*count)++] = i * 8u + shift; + } + } + } +} + +bool contains_payload(const std::uint8_t* frame, std::size_t size, std::uint8_t wanted, + std::size_t* first_bit) { + for (std::size_t at = 0; at + 1u < size; ++at) { + if (frame[at] != 0x58u || frame[at + 1u] != 0x38u) continue; + Container container; + if (parse_container(frame, size * 8u, at * 8u, &container) && container.has(wanted)) { + if (first_bit != nullptr) *first_bit = at * 8u; + return true; + } + } + for (std::size_t shift = 1; shift < 8u; ++shift) { + const std::size_t aligned_len = size - 1u; + for (std::size_t i = 0; i + 1u < aligned_len; ++i) { + const std::uint8_t first = static_cast( + ((static_cast(frame[i]) << shift) | + (static_cast(frame[i + 1u]) >> (8u - shift))) & + 0xFFu); + const std::uint8_t second = static_cast( + ((static_cast(frame[i + 1u]) << shift) | + (static_cast(frame[i + 2u]) >> (8u - shift))) & + 0xFFu); + if (first != 0x58u || second != 0x38u) continue; + Container container; + if (parse_container(frame, size * 8u, i * 8u + shift, &container) && + container.has(wanted)) { + if (first_bit != nullptr) *first_bit = i * 8u + shift; + return true; + } + } + } + return false; +} + +} // namespace + +namespace { + +std::uint32_t read_bits(const std::uint8_t* data, std::size_t start, std::size_t count) { + std::uint32_t value = 0; + for (std::size_t index = start; index < start + count; ++index) { + value = (value << 1) | ((data[index >> 3] >> (7u - (index & 7u))) & 1u); + } + return value; +} + +// AC-3 syncframe length in 16-bit words, indexed by fscod then frmsizecod. +const std::uint16_t kAc3FrameWords[3][38] = { + {64, 64, 80, 80, 96, 96, 112, 112, 128, 128, 160, 160, 192, 192, 224, 224, + 256, 256, 320, 320, 384, 384, 448, 448, 512, 512, 640, 640, 768, 768, + 896, 896, 1024, 1024, 1152, 1152, 1280, 1280}, + {69, 70, 87, 88, 104, 105, 121, 122, 139, 140, 174, 175, 208, 209, 243, 244, + 278, 278, 348, 348, 417, 418, 487, 487, 557, 557, 696, 696, 835, 835, + 975, 975, 1114, 1114, 1253, 1253, 1393, 1393}, + {96, 96, 120, 120, 144, 144, 168, 168, 192, 192, 240, 240, 288, 288, 336, 336, + 384, 384, 480, 480, 576, 576, 672, 672, 768, 768, 960, 960, 1152, 1152, + 1344, 1344, 1536, 1536, 1728, 1728, 1920, 1920}, +}; + +} // namespace + +std::size_t frame_header_at(const std::uint8_t* data, std::size_t size, std::size_t offset, + FrameHeader* out) { + if (data == nullptr || offset + 6u > size) return 0; + const std::uint16_t syncword = + static_cast((static_cast(data[offset]) << 8) | data[offset + 1]); + if (syncword != kEac3Syncword) return 0; + const std::size_t base = offset * 8u; + const std::uint32_t bsid = read_bits(data, base + 40u, 5u); + if (bsid <= 8u) { + const std::uint32_t fscod = read_bits(data, base + 32u, 2u); + const std::uint32_t frmsizecod = read_bits(data, base + 34u, 6u); + if (fscod > 2u || frmsizecod >= 38u) return 0; + if (out != nullptr) { + out->frame_bytes = static_cast(kAc3FrameWords[fscod][frmsizecod]) * 2u; + out->offset = offset; + out->codec = 0; + out->strmtyp = 0; + out->substreamid = 0; + } + return static_cast(kAc3FrameWords[fscod][frmsizecod]) * 2u; + } + const std::size_t words = + (static_cast(data[offset + 2] & 0x07u) << 8) | data[offset + 3]; + if (out != nullptr) { + out->frame_bytes = (words + 1u) * 2u; + out->offset = offset; + out->codec = 1; + out->strmtyp = static_cast(read_bits(data, base + 16u, 2u)); + out->substreamid = static_cast(read_bits(data, base + 18u, 3u)); + } + return (words + 1u) * 2u; +} + +std::size_t frame_bytes_at(const std::uint8_t* data, std::size_t size, std::size_t offset) { + return frame_header_at(data, size, offset, nullptr); +} + +std::size_t audio_frame_bytes_at(const std::uint8_t* data, std::size_t size, std::size_t offset, + bool end_of_stream) { + constexpr std::size_t kMaxSubstreams = 8; + FrameHeader seen[kMaxSubstreams]; + std::size_t count = 0; + std::size_t consumed = 0; + while (count < kMaxSubstreams) { + FrameHeader header; + const std::size_t bytes = frame_header_at(data, size, offset + consumed, &header); + if (bytes == 0 || offset + consumed + bytes > size) break; + bool repeats = false; + for (std::size_t index = 0; index < count; ++index) { + if (seen[index].same_stream(header)) { + repeats = true; + break; + } + } + if (repeats) return consumed; + seen[count++] = header; + consumed += bytes; + } + if (count != 0u && consumed != 0u && end_of_stream) return consumed; + return 0; +} + +bool joc_config_idx(const std::uint8_t* frame, std::size_t frame_bytes, unsigned* out) { + if (out == nullptr || frame == nullptr || frame_bytes < 8u) return false; + std::size_t offsets[4096]; + std::size_t count = 0; + marker_offsets(frame, frame_bytes, offsets, 4096, &count); + for (std::size_t i = 0; i < count; ++i) { + Container candidate; + if (!parse_container(frame, frame_bytes * 8u, offsets[i], &candidate)) continue; + if (!candidate.has(kIdOamd) || !candidate.has(kIdJoc)) continue; + for (std::size_t p = 0; p < candidate.payload_count; ++p) { + if (candidate.payloads[p].id != kIdJoc) continue; + // joc_dmx_config_idx is the first 3 bits of the JOC payload, followed by + // joc_num_objects_bits (6) and joc_ext_config_idx (3). + const std::size_t bit = candidate.payloads[p].bit_offset; + std::uint32_t value = 0; + for (unsigned index = 0; index < 3u; ++index) { + const std::size_t position = bit + index; + if (position / 8u >= frame_bytes) return false; + value = (value << 1) | ((frame[position / 8u] >> (7u - (position % 8u))) & 1u); + } + *out = value; + return true; + } + } + return false; +} + +bool frame_has_joc(const std::uint8_t* frame, std::size_t frame_bytes) { + if (frame == nullptr || frame_bytes < 8u) return false; + + std::size_t offsets[4096]; + std::size_t count = 0; + marker_offsets(frame, frame_bytes, offsets, 4096, &count); + + Container matches[16]; + std::size_t match_count = 0; + for (std::size_t i = 0; i < count; ++i) { + Container candidate; + if (!parse_container(frame, frame_bytes * 8u, offsets[i], &candidate)) continue; + if (candidate.has(kIdOamd) && candidate.has(kIdJoc)) { + if (match_count < 16) matches[match_count++] = candidate; + } + } + if (match_count == 0) return false; + + // A payload may contain bytes that look like another container; only + // top-level ones count. + Container top_level[16]; + std::size_t top_count = 0; + for (std::size_t i = 0; i < match_count; ++i) { + bool nested = false; + for (std::size_t j = 0; j < top_count; ++j) { + if (top_level[j].start_bit < matches[i].start_bit && + matches[i].start_bit < top_level[j].start_bit + top_level[j].raw_size * 8u) { + nested = true; + break; + } + } + if (!nested && top_count < 16) top_level[top_count++] = matches[i]; + } + // Exactly one is what the core requires; more than one is ambiguous there. + return top_count == 1u; +} + +ScanResult scan(const std::uint8_t* data, std::size_t size, std::size_t max_frames) { + ScanResult result; + if (data == nullptr || size < 8u) { + result.detail = "buffer too small"; + return result; + } + + std::size_t offset = 0; + std::size_t frames = 0; + std::size_t with_joc = 0; + bool first = true; + while (frames < max_frames) { + const std::size_t frame_bytes = frame_bytes_at(data, size, offset); + if (frame_bytes == 0) { + result.detail = frames == 0 ? "no E-AC-3 syncword at the start" : "stream walk ended"; + break; + } + if (offset + frame_bytes > size) { + result.detail = "buffer ends inside a syncframe"; + break; + } + if (first) { + result.first_frame_bytes = frame_bytes; + first = false; + } else if (frame_bytes != result.first_frame_bytes) { + result.all_frames_same_size = false; + } + if (frame_has_joc(data + offset, frame_bytes)) ++with_joc; + ++frames; + offset += frame_bytes; + } + + result.frames_examined = frames; + result.frames_with_joc = with_joc; + if (frames == 0) { + result.joc = JocState::kUnknown; + if (result.detail[0] == '\0') result.detail = "no syncframes"; + } else if (with_joc != 0) { + result.joc = JocState::kYes; + result.detail = (with_joc == frames) + ? "every examined syncframe carries the JOC EMDF container" + : "the JOC EMDF container is present in part of the examined " + "audio frames (dependent substream or a late first frame)"; + } else { + result.joc = JocState::kNo; + result.detail = "no examined syncframe carries a JOC EMDF container"; + } + return result; +} + +} // namespace joc_eac3 diff --git a/src/eac3_scan.h b/src/eac3_scan.h new file mode 100644 index 0000000..03611e5 --- /dev/null +++ b/src/eac3_scan.h @@ -0,0 +1,83 @@ +// E-AC-3 syncframe walking and JOC detection. +// +// The plugin must decide "is this file E-AC-3 JOC" from the bitstream alone, +// because container metadata (MP4 dec3, Matroska A_EAC3) says only "E-AC-3" and +// the JOC flag inside it is frequently missing. +// +// A syncframe carries JOC when it holds exactly one top-level EMDF container +// (syncword 0x5838, any of the eight bit alignments) whose payload list contains +// both ID11 (OAMD) and ID14 (JOC) — the same per-frame test the rendering core +// applies. The stream counts as JOC when at least one examined audio frame +// carries one: in a 7-channel program the JOC payload lives in the dependent +// substream while the independent substream is a plain 5.1 core, and an AC-3 +// core may precede it, so "every syncframe carries JOC" is not a valid rule. +// The first audio frame may also carry no metadata at all. +#pragma once + +#include +#include + +namespace joc_eac3 { + +// Syncframe header fields the plugin needs. codec/strmtyp/substreamid identify +// the substream: within one audio frame each combination appears once, which is +// what turns a syncframe stream into audio frames. +struct FrameHeader { + std::size_t frame_bytes = 0; + std::size_t offset = 0; + std::uint8_t codec = 0; // 0 = AC-3, 1 = E-AC-3 + std::uint8_t strmtyp = 0; + std::uint8_t substreamid = 0; + + bool same_stream(const FrameHeader& other) const { + return codec == other.codec && strmtyp == other.strmtyp && + substreamid == other.substreamid; + } +}; + +enum class JocState { + kYes, // at least one examined syncframe carried a JOC EMDF container + kNo, // no examined syncframe carried one + kUnknown, // not enough data, or the stream is not walkable ac3/eac3 +}; + +struct ScanResult { + JocState joc = JocState::kUnknown; + std::size_t frames_examined = 0; + std::size_t frames_with_joc = 0; + std::size_t first_frame_bytes = 0; + bool all_frames_same_size = true; + const char* detail = ""; +}; + +// Walks up to `max_frames` syncframes of `data` and classifies the stream. +ScanResult scan(const std::uint8_t* data, std::size_t size, std::size_t max_frames); + +// Length of the syncframe starting at data[offset], or 0 when there is no valid +// header there. AC-3 and E-AC-3 are told apart by bsid exactly as the core does: +// bsid <= 8 sizes the frame from fscod/frmsizecod, anything above uses frmsiz. +std::size_t frame_bytes_at(const std::uint8_t* data, std::size_t size, std::size_t offset); + +// Same, and fills the substream identity. Returns 0 when no header is there. +std::size_t frame_header_at(const std::uint8_t* data, std::size_t size, std::size_t offset, + FrameHeader* out); + +// Length of the whole audio frame starting at data[offset]: every syncframe up to +// (and excluding) the first repeated (codec, strmtyp, substreamid) combination. +// A 7-channel program interleaves an independent and a dependent substream, so one +// audio frame is two syncframes and one bed frame. +// +// Returns 0 when the group is still open inside the buffer -- the caller has to ask +// again with more data -- unless `end_of_stream` says no more bytes will arrive, in +// which case the trailing group is complete by definition. +std::size_t audio_frame_bytes_at(const std::uint8_t* data, std::size_t size, std::size_t offset, + bool end_of_stream); + +// Reads joc_dmx_config_idx (the first 3 bits of the JOC payload) out of one +// syncframe. False when the frame carries no JOC payload. +bool joc_config_idx(const std::uint8_t* frame, std::size_t frame_bytes, unsigned* out); + +// True when this single syncframe carries the JOC EMDF container. +bool frame_has_joc(const std::uint8_t* frame, std::size_t frame_bytes); + +} // namespace joc_eac3 diff --git a/src/joc_decode.cpp b/src/joc_decode.cpp new file mode 100644 index 0000000..29fc866 --- /dev/null +++ b/src/joc_decode.cpp @@ -0,0 +1,1472 @@ +#include "joc_decode.h" + +#include + +#include +#include +#include +#include +#include +#include + +// The renderer is the shared joc_core library (joc_core.dll), resolved at run +// time by load_api(); the headers are the ones its build exports. +#include +#include + +#include "eac3_scan.h" +#include "log.h" +#include "win_path.h" + +namespace joc_decode { + +std::string component_directory(); + +namespace { + +constexpr std::size_t kEac3Chunk = 96u * 1024u; // bytes read per push +// The core renders during the push, so a read queues about as much as it is +// about to consume rather than everything it just read. +constexpr std::uint64_t kEac3FramesPerRead = 3u; +// Rendered audio the caller has not taken yet. +constexpr std::size_t kMaxRenderedAheadSamples = 4096u; +constexpr std::size_t kBedFramesChunk = 8192u; // staging capacity, in frames +// The bed channel count follows joc_dmx_config_idx: the 5.1 configurations +// (0 and 3) decode to 6 channels through `ffmpeg -ac 6`, the 7-channel ones +// (1, 2 and 4) to 8 channels in the decoder's own layout. See bed_channels. +constexpr std::size_t kDefaultBedChannels = 6; +constexpr std::size_t kMaxBedChannels = 8; +// A read on an anonymous pipe only completes once the whole request is available, +// so each read asks for a slice ffmpeg can always fill, and the pipe buffer is +// sized well above that slice. Requesting the whole staging buffer deadlocks: +// ffmpeg fills the pipe and blocks, while the reader waits for more than the pipe +// can ever hold. +constexpr std::size_t kBedReadBytes = 48u * 1024u; +constexpr std::size_t kBedPipeBytes = 1u << 20; +constexpr std::size_t kFrameSamples = JOC_FRAME_SAMPLES; + +// The decoded bed has to stay on the E-AC-3 frame grid that the JOC matrix and the +// OAMD are indexed by. An mp4/mov edit list trims the decoded audio instead, which +// takes the bed off that grid by however much the list removes -- a Dolby Atmos +// download loses 2432 samples (1.58 frames) -- and every frame's matrix would then be +// applied to audio tens of milliseconds away from it, so a subset of the objects comes +// out attenuated. The demuxer's own option drops the trim; the option exists only on +// the mov/mp4 demuxer, so it is passed for that family alone. +bool has_mov_timeline(const std::string& path) { + static const char* const kExtensions[] = {".mp4", ".m4a", ".m4b", ".m4v", + ".mov", ".3gp", ".3g2", ".mj2"}; + std::string lowered = path; + for (char& character : lowered) { + if (character >= 'A' && character <= 'Z') { + character = static_cast(character - 'A' + 'a'); + } + } + for (const char* extension : kExtensions) { + const std::size_t length = std::strlen(extension); + if (lowered.size() >= length && + lowered.compare(lowered.size() - length, length, extension) == 0) { + return true; + } + } + return false; +} + +// joc_dmx_config_idx of the first syncframe in the window that carries JOC, or -1 +// when the window holds none. Only the first three bits of the JOC payload are +// read, so this costs nothing next to a decode. +int scan_config_idx(const std::uint8_t* data, std::size_t size) { + std::size_t offset = 0; + while (offset + 6u <= size) { + const std::size_t bytes = joc_eac3::frame_bytes_at(data, size, offset); + if (bytes == 0 || offset + bytes > size) break; + if (joc_eac3::frame_has_joc(data + offset, bytes)) { + unsigned config = 0; + if (joc_eac3::joc_config_idx(data + offset, bytes, &config)) { + return static_cast(config); + } + } + offset += bytes; + } + return -1; +} + +// True when the JOC configuration declares 7 core channels. +bool seven_channel_config(int config) { + return config == 1 || config == 2 || config == 4; +} + +// --------------------------------------------------------------------------- +// Kernel entry points. +// +// The kernel's own C++ sources are part of this component (see kernel/, a copy of +// the project's source tree), so the public C ABI is linked in directly. There is +// nothing to load at run time, and no way for the component and the renderer to +// disagree about which ABI they were built against. +// --------------------------------------------------------------------------- +struct CoreApi { + joc_error(JOC_CALL* create)(const joc_stream_config*, joc_stream**) = nullptr; + joc_error(JOC_CALL* push)(joc_stream*, const joc_stream_buffer*, std::uint32_t*, + std::uint32_t*) = nullptr; + joc_error(JOC_CALL* pull)(joc_stream*, joc_stream_buffer*, std::uint32_t*) = nullptr; + joc_error(JOC_CALL* flush)(joc_stream*) = nullptr; + joc_error(JOC_CALL* reset)(joc_stream*) = nullptr; + joc_error(JOC_CALL* status)(const joc_stream*, joc_stream_status_info*) = nullptr; + joc_error(JOC_CALL* destroy)(joc_stream*) = nullptr; + std::uint32_t(JOC_CALL* abi_version)() = nullptr; + const char*(JOC_CALL* version_string)() = nullptr; + const char*(JOC_CALL* error_name)(joc_error) = nullptr; + const char*(JOC_CALL* last_error_detail)() = nullptr; +}; + +bool file_exists(const std::string& path) { + const std::wstring wide = joc_path::to_wide_extended(path); + if (wide.empty()) return false; + const DWORD attributes = GetFileAttributesW(wide.c_str()); + return attributes != INVALID_FILE_ATTRIBUTES && + (attributes & FILE_ATTRIBUTE_DIRECTORY) == 0; +} + +// The renderer is joc_core.dll, the library the reference CLI and the upstream +// component use, so a session renders bit-identically to those frontends. An +// explicit path wins, then the plugin's own directory (and its parent, which is +// where a build tree keeps the library), then the bare name. +bool load_api(const std::string& explicit_path, CoreApi* api, std::string* error) { + std::wstring candidates[4]; + int count = 0; + if (!explicit_path.empty()) candidates[count++] = joc_path::to_wide_extended(explicit_path); + const std::string directory = component_directory(); + if (!directory.empty()) { + candidates[count++] = joc_path::to_wide_extended(directory + "\\joc_core.dll"); + candidates[count++] = joc_path::to_wide_extended(directory + "\\..\\joc_core.dll"); + } + candidates[count++] = L"joc_core.dll"; + + HMODULE module = nullptr; + std::wstring last_attempt; + for (int index = 0; index < count; ++index) { + last_attempt = candidates[index]; + module = LoadLibraryExW(candidates[index].c_str(), nullptr, + LOAD_WITH_ALTERED_SEARCH_PATH); + if (module != nullptr) break; + } + if (module == nullptr) { + if (error != nullptr) { + *error = "cannot load joc_core.dll; put it next to joc_mpv.dll or set joc-core"; + } + return false; + } + + auto symbol = [module](const char* name) -> FARPROC { + return GetProcAddress(module, name); + }; + api->create = reinterpret_castcreate)>(symbol("joc_stream_create")); + api->push = reinterpret_castpush)>(symbol("joc_stream_push")); + api->pull = reinterpret_castpull)>(symbol("joc_stream_pull")); + api->flush = reinterpret_castflush)>(symbol("joc_stream_flush")); + api->reset = reinterpret_castreset)>(symbol("joc_stream_reset")); + api->status = reinterpret_caststatus)>(symbol("joc_stream_status")); + api->destroy = reinterpret_castdestroy)>(symbol("joc_stream_destroy")); + api->abi_version = reinterpret_castabi_version)>(symbol("joc_abi_version")); + api->version_string = + reinterpret_castversion_string)>(symbol("joc_version_string")); + api->error_name = reinterpret_casterror_name)>(symbol("joc_error_name")); + api->last_error_detail = + reinterpret_castlast_error_detail)>(symbol("joc_last_error_detail")); + if (api->create == nullptr || api->push == nullptr || api->pull == nullptr || + api->flush == nullptr || api->reset == nullptr || api->status == nullptr || + api->destroy == nullptr || api->abi_version == nullptr) { + if (error != nullptr) *error = "joc_core.dll does not export the streaming API"; + return false; + } + if (api->abi_version() != JOC_ABI_VERSION) { + if (error != nullptr) *error = "joc_core.dll has an unexpected ABI"; + return false; + } + return true; +} + +const char* error_text(const CoreApi& api, joc_error code) { + if (api.error_name != nullptr) { + const char* name = api.error_name(code); + if (name != nullptr) return name; + } + return "unknown core error"; +} + +// The core keeps a structured detail for the last failing call ("eac3: chanmap +// declares [Lts,Rts] but joc_dmx_config_idx=2 expects [Vhl,Vhr]"). The plugin +// reports the variant rather than only its error code, so a stream the renderer +// deliberately refuses says why. +std::string error_with_detail(const CoreApi& api, joc_error code) { + std::string text = error_text(api, code); + if (api.last_error_detail != nullptr) { + const char* detail = api.last_error_detail(); + if (detail != nullptr && *detail != '\0') { + text += ": "; + text += detail; + } + } + return text; +} + +// --------------------------------------------------------------------------- +// ffmpeg child process producing the 5.1 core PCM on a pipe. +// --------------------------------------------------------------------------- +class FfmpegPipe { +public: + ~FfmpegPipe() { stop(); } + + // ffmpeg_path, the input file and whatever should follow "-i " are + // separate: the 5.1 bed and the E-AC-3 metadata stream of a container file are + // both ffmpeg output, they only differ in those arguments. input_arguments come + // before -i and carry the decoder options the bed needs. + bool start(const std::string& ffmpeg_path, const std::string& input_path, + const std::wstring& input_arguments, const std::wstring& output_arguments, + const char* label, const std::wstring& stderr_path, std::string* error, + std::size_t pipe_bytes = kBedPipeBytes) { + SECURITY_ATTRIBUTES attributes{}; + attributes.nLength = sizeof(attributes); + attributes.bInheritHandle = TRUE; + HANDLE read_end = nullptr; + HANDLE write_end = nullptr; + if (CreatePipe(&read_end, &write_end, &attributes, static_cast(pipe_bytes)) == FALSE) { + if (error != nullptr) *error = std::string("cannot create the ") + label + " pipe"; + return false; + } + // Only the child's end is inheritable. + SetHandleInformation(read_end, HANDLE_FLAG_INHERIT, 0); + + HANDLE null_input = CreateFileW(L"NUL", GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_WRITE, + &attributes, OPEN_EXISTING, 0, nullptr); + HANDLE error_file = CreateFileW(stderr_path.c_str(), GENERIC_WRITE, + FILE_SHARE_READ | FILE_SHARE_WRITE, &attributes, + CREATE_ALWAYS, 0, nullptr); + + std::wstring command = L"\"" + joc_path::to_wide_extended(ffmpeg_path) + L"\""; + command += L" -hide_banner -loglevel error -nostdin -y "; + command += input_arguments; // input options must precede -i + command += L" -i \""; + command += joc_path::to_wide_extended(input_path); + command += L"\" "; + command += output_arguments; + + STARTUPINFOW startup{}; + startup.cb = sizeof(startup); + startup.dwFlags = STARTF_USESTDHANDLES; + startup.hStdInput = null_input; + startup.hStdOutput = write_end; + startup.hStdError = (error_file != INVALID_HANDLE_VALUE) ? error_file : null_input; + + PROCESS_INFORMATION process{}; + std::vector mutable_command(command.begin(), command.end()); + mutable_command.push_back(L'\0'); + const BOOL created = CreateProcessW(nullptr, mutable_command.data(), nullptr, nullptr, + TRUE, CREATE_NO_WINDOW, nullptr, nullptr, &startup, + &process); + CloseHandle(write_end); + if (null_input != INVALID_HANDLE_VALUE) CloseHandle(null_input); + if (error_file != INVALID_HANDLE_VALUE) CloseHandle(error_file); + if (created == FALSE) { + CloseHandle(read_end); + if (error != nullptr) *error = std::string("cannot start ffmpeg for the ") + label; + return false; + } + CloseHandle(process.hThread); + pipe_ = read_end; + process_ = process.hProcess; + joc_log::line("core %s: ffmpeg started (pid %lu)", label, process.dwProcessId); + return true; + } + + // Returns bytes read; 0 means end of stream. + std::size_t read(void* destination, std::size_t bytes) { + if (pipe_ == nullptr) return 0; + DWORD got = 0; + if (ReadFile(pipe_, destination, static_cast(bytes), &got, nullptr) == FALSE) { + return 0; + } + return got; + } + + void stop() { + if (pipe_ != nullptr) { + CloseHandle(pipe_); + pipe_ = nullptr; + } + if (process_ != nullptr) { + // ffmpeg is normally gone by now (its stdout was drained); ask it to + // finish rather than killing it, and only then let go. + if (WaitForSingleObject(process_, 5000) == WAIT_TIMEOUT) { + TerminateProcess(process_, 1); + } + CloseHandle(process_); + process_ = nullptr; + } + } + + bool finished() const { return pipe_ == nullptr; } + +private: + HANDLE pipe_ = nullptr; + HANDLE process_ = nullptr; +}; + +// --------------------------------------------------------------------------- +// Small file reader (wide paths, no CRT locale involved). +// --------------------------------------------------------------------------- +class InputFile { +public: + ~InputFile() { close(); } + bool open(const std::string& path) { + handle_ = CreateFileW(joc_path::to_wide_extended(path).c_str(), GENERIC_READ, + FILE_SHARE_READ | FILE_SHARE_WRITE, nullptr, OPEN_EXISTING, + FILE_ATTRIBUTE_NORMAL | FILE_FLAG_SEQUENTIAL_SCAN, nullptr); + return handle_ != INVALID_HANDLE_VALUE; + } + bool is_open() const { return handle_ != INVALID_HANDLE_VALUE; } + std::size_t read(void* destination, std::size_t bytes) { + if (handle_ == INVALID_HANDLE_VALUE) return 0; + DWORD got = 0; + if (ReadFile(handle_, destination, static_cast(bytes), &got, nullptr) == FALSE) { + return 0; + } + return got; + } + bool seek(std::uint64_t offset) { + if (handle_ == INVALID_HANDLE_VALUE) return false; + LARGE_INTEGER value{}; + value.QuadPart = static_cast(offset); + return SetFilePointerEx(handle_, value, nullptr, FILE_BEGIN) != FALSE; + } + std::uint64_t size() const { + LARGE_INTEGER value{}; + if (handle_ == INVALID_HANDLE_VALUE || GetFileSizeEx(handle_, &value) == FALSE) return 0; + return static_cast(value.QuadPart); + } + void close() { + if (handle_ != INVALID_HANDLE_VALUE) { + CloseHandle(handle_); + handle_ = INVALID_HANDLE_VALUE; + } + } + +private: + HANDLE handle_ = INVALID_HANDLE_VALUE; +}; + +const char* const kLayouts[] = {"2.0", "3.0", "3.1", "4.0", "5.0", "5.1", "5.1.2", + "5.1.4", "6.1", "7.0", "7.1", "7.1.2", "7.1.4", "9.1.4", + "9.1.6"}; +const unsigned kLayoutChannels[] = {2, 3, 4, 4, 5, 6, 8, 10, 7, 7, 8, 10, 12, 14, 16}; + +// Every ffmpeg child writes its diagnostics next to the component rather than into +// whatever working directory the host process happens to have; separate files so +// no child can truncate another's. +std::wstring stderr_path_for(const wchar_t* name) { + // A host that sets JOC_LOG (the mpv plugin does, to keep diagnostics out of + // the directory mpv scans for scripts) gets the child logs beside it. + wchar_t configured[4096] = {}; + const DWORD configured_length = + GetEnvironmentVariableW(L"JOC_LOG", configured, static_cast(4096)); + if (configured_length > 0 && configured_length < 4096) { + const std::wstring log_path(configured, configured_length); + const std::wstring::size_type slash = log_path.find_last_of(L"\\/"); + if (slash != std::wstring::npos) return log_path.substr(0, slash) + L"\\" + name; + } + HMODULE self = nullptr; + GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS | + GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, + reinterpret_cast(&speaker_channels), &self); + wchar_t path[4096] = {}; + const DWORD length = GetModuleFileNameW(self, path, 4096); + if (length == 0) return std::wstring(name); + const std::wstring text(path, length); + const std::wstring::size_type slash = text.find_last_of(L"\\/"); + return slash == std::wstring::npos ? std::wstring(name) + : text.substr(0, slash) + L"\\" + name; +} + +// The time ffmpeg's -ss takes for a given source sample. A seek always starts on +// a syncframe boundary, so the sample is exactly representable in microseconds. +std::wstring seek_time(std::uint64_t source_sample) { + if (source_sample == 0) return {}; + wchar_t text[64] = {}; + std::swprintf(text, 64, L"%.6f", static_cast(source_sample) / 48000.0); + return text; +} + +// Source sample a time offset names, rounded the way the core rounds a position +// (pfc::rint64, i.e. llrint: to nearest, ties to even). +std::int64_t sample_of_seconds(double seconds) { + if (!(seconds > 0.0)) return 0; // also catches NaN + const double value = seconds * 48000.0; + if (value >= 9.0e18) return 9223372036854775807LL; + return static_cast(std::llrint(value)); +} + +} // namespace + +const char* const* speaker_layouts(std::size_t* count) { + if (count != nullptr) *count = sizeof(kLayouts) / sizeof(kLayouts[0]); + return kLayouts; +} + +unsigned speaker_channels(const std::string& layout) { + for (std::size_t i = 0; i < sizeof(kLayouts) / sizeof(kLayouts[0]); ++i) { + if (layout == kLayouts[i]) return kLayoutChannels[i]; + } + return 0; +} + +namespace { + +// The core's conversion, reproduced: kernel/src/io/wav_writer.cpp:to_int32. +// (min)() is written that way because the test tools compile this file without +// NOMINMAX, and windows.h's min macro would otherwise swallow the call. +std::int32_t to_int32(const float value) { + if (!std::isfinite(value)) { + return (std::numeric_limits::min)(); + } + return static_cast(value); +} + +} // namespace + +Int24Block pack_int24(const float* interleaved, std::size_t count, std::uint8_t* out) { + Int24Block block; + for (std::size_t i = 0; i < count; ++i) { + float value = interleaved[i]; + if (value > 1.0f) { + value = 1.0f; + ++block.clipped; + } else if (value < -1.0f) { + value = -1.0f; + ++block.clipped; + } + const std::int32_t scaled = to_int32(value * 8388607.0f); + const std::uint32_t bits = static_cast(scaled); + out[i * 3 + 0] = static_cast(bits & 0xFFu); + out[i * 3 + 1] = static_cast((bits >> 8) & 0xFFu); + out[i * 3 + 2] = static_cast((bits >> 16) & 0xFFu); + // What the host will read back is the sign-extended low 24 bits. + std::int32_t written = static_cast(bits & 0xFFFFFFu); + if ((written & 0x800000) != 0) written -= 0x1000000; + const std::int32_t magnitude = (written < 0) ? -written : written; + if (magnitude > block.peak) block.peak = magnitude; + } + return block; +} + +std::string component_directory() { + HMODULE self = nullptr; + if (GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS | + GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, + reinterpret_cast(&component_directory), &self) == FALSE) { + return {}; + } + wchar_t path[4096] = {}; + const DWORD length = GetModuleFileNameW(self, path, 4096); + if (length == 0) return {}; + const std::wstring text(path, length); + const std::wstring::size_type slash = text.find_last_of(L"\\/"); + if (slash == std::wstring::npos) return {}; + const std::wstring directory = text.substr(0, slash); + const int needed = WideCharToMultiByte(CP_UTF8, 0, directory.c_str(), + static_cast(directory.size()), nullptr, 0, + nullptr, nullptr); + std::string out(static_cast(needed), '\0'); + WideCharToMultiByte(CP_UTF8, 0, directory.c_str(), static_cast(directory.size()), + out.data(), needed, nullptr, nullptr); + return out; +} + +std::string resolve_hrtf_file(const Settings& settings) { + if (!settings.hrtf_file.empty()) return settings.hrtf_file; + const std::string directory = component_directory(); + if (directory.empty()) return {}; + // Same convention as the reference CLI next to its executable: + // \HRTF\binaural.sofa or \HRTF\binaural.personalized_headphone. + const char* name = (settings.hrtf_source == HrtfSource::kRosella) + ? "binaural.personalized_headphone" + : "binaural.sofa"; + return directory + "\\HRTF\\" + name; +} + +FileProbe probe_file(const std::string& path, std::size_t max_scan_bytes, + std::uint64_t start_offset) { + FileProbe probe; + InputFile file; + if (!file.open(path)) { + probe.detail = "cannot open"; + return probe; + } + const std::uint64_t size = file.size(); + if (start_offset >= size) { + probe.detail = "file too small to be E-AC-3"; + return probe; + } + if (start_offset != 0 && !file.seek(start_offset)) { + probe.detail = "cannot skip the leading tag area"; + return probe; + } + const std::uint64_t stream_bytes = size - start_offset; + + // A Media Library scan calls this for every file, so the whole stream is + // walked only when that is cheap; otherwise the first window is enough, + // because E-AC-3 syncframes in a stream like this are all the same size. + const std::uint64_t kFullWalkLimit = 16u * 1024u * 1024u; + const std::size_t window = + (max_scan_bytes != 0) ? max_scan_bytes : 256u * 1024u; + std::vector buffer(static_cast( + (stream_bytes < kFullWalkLimit && stream_bytes > 0) ? stream_bytes : window)); + const std::size_t got = file.read(buffer.data(), buffer.size()); + if (got < 8) { + probe.detail = "file too small to be E-AC-3"; + return probe; + } + + const joc_eac3::ScanResult scan = joc_eac3::scan(buffer.data(), got, 8); + probe.readable = true; + probe.joc = (scan.joc == joc_eac3::JocState::kYes); + probe.detail = scan.detail; + if (scan.frames_examined == 0 || scan.first_frame_bytes == 0) { + probe.detail = "not a bare E-AC-3 stream"; + return probe; + } + + // The renderer pairs one audio frame with exactly 1536 bed samples, so the + // stream length is counted in audio frames: a 7-channel program interleaves an + // independent and a dependent substream, and one audio frame is two syncframes. + const bool whole_file = (buffer.size() == stream_bytes); + std::size_t offset = 0; + std::size_t first_audio_frame = 0; + bool same_audio_frame_size = true; + std::uint64_t seen = 0; + while (true) { + const std::size_t bytes = + joc_eac3::audio_frame_bytes_at(buffer.data(), got, offset, whole_file); + if (bytes == 0 || offset + bytes > got) break; + if (seen == 0) { + first_audio_frame = bytes; + } else if (bytes != first_audio_frame) { + same_audio_frame_size = false; + } + offset += bytes; + ++seen; + } + + std::uint64_t frames = 0; + if (whole_file) { + frames = seen; + probe.detail = "frame count walked over the whole file"; + } else if (seen != 0 && same_audio_frame_size) { + frames = stream_bytes / first_audio_frame; + probe.detail = "frame count extrapolated from a constant frame size"; + } else if (offset != 0) { + // Variable frame size: count in the window and scale by the byte ratio. + frames = static_cast( + (static_cast(stream_bytes) / static_cast(offset)) * + static_cast(seen)); + probe.detail = "frame count estimated from a variable frame size"; + } + + const int config = scan_config_idx(buffer.data(), got); + probe.frames = frames; + probe.sample_rate = 48000; + // Core audio channel count: the 5.1 configurations give 6, the 7-channel ones 8. + probe.channels = static_cast(seven_channel_config(config) ? 8 : 6); + probe.duration_seconds = + static_cast(frames) * static_cast(kFrameSamples) / 48000.0; + return probe; +} + +// --------------------------------------------------------------------------- +// JOC verdict for a container file, without rendering anything. +// --------------------------------------------------------------------------- +bool probe_container_joc(const std::string& ffmpeg_path, const std::string& path, + unsigned audio_index, bool* joc, std::string* detail) { + struct Entry { + std::string path; + unsigned audio_index = 0; + std::uint64_t size = 0; + std::uint64_t modified = 0; + bool joc = false; + std::string detail; + }; + static std::vector cache; + + std::uint64_t size = 0; + std::uint64_t modified = 0; + { + WIN32_FILE_ATTRIBUTE_DATA data{}; + if (GetFileAttributesExW(joc_path::to_wide_extended(path).c_str(), GetFileExInfoStandard, + &data) != FALSE) { + size = (static_cast(data.nFileSizeHigh) << 32) | data.nFileSizeLow; + modified = (static_cast(data.ftLastWriteTime.dwHighDateTime) << 32) | + data.ftLastWriteTime.dwLowDateTime; + } + } + for (const Entry& entry : cache) { + if (entry.path == path && entry.audio_index == audio_index && entry.size == size && + entry.modified == modified) { + if (joc != nullptr) *joc = entry.joc; + if (detail != nullptr) *detail = entry.detail; + return true; + } + } + + if (ffmpeg_path.empty()) { + if (detail != nullptr) *detail = "no ffmpeg configured"; + return false; + } + + FfmpegPipe pipe; + std::string error; + std::wstring arguments = L"-map 0:a:"; + arguments += std::to_wstring(audio_index); + arguments += L" -vn -t 3 -c:a copy -f eac3 -"; + const std::wstring stderr_path = [] { + wchar_t temp[MAX_PATH + 1] = {}; + const DWORD length = GetTempPathW(MAX_PATH, temp); + return length == 0 ? std::wstring(L"NUL") + : std::wstring(temp) + L"joc_container_probe.log"; + }(); + if (!pipe.start(ffmpeg_path, path, L"", arguments, "probe", stderr_path, &error, 1u << 20)) { + if (detail != nullptr) *detail = error; + return false; + } + + std::vector prefix(512u * 1024u); + std::size_t filled = 0; + while (filled < prefix.size()) { + const std::size_t got = pipe.read(prefix.data() + filled, prefix.size() - filled); + if (got == 0) break; + filled += got; + } + pipe.stop(); + + const joc_eac3::ScanResult scan = joc_eac3::scan(prefix.data(), filled, 8); + const bool carries_joc = (scan.joc == joc_eac3::JocState::kYes); + + Entry entry; + entry.path = path; + entry.audio_index = audio_index; + entry.size = size; + entry.modified = modified; + entry.joc = carries_joc; + entry.detail = scan.detail; + if (cache.size() >= 8) cache.erase(cache.begin()); + cache.push_back(entry); + + joc_log::line("container: %s track %u -> %s (%s)", path.c_str(), audio_index, + carries_joc ? "JOC" : "not JOC", scan.detail); + if (joc != nullptr) *joc = carries_joc; + if (detail != nullptr) *detail = scan.detail; + return true; +} + +// --------------------------------------------------------------------------- +// Engine +// --------------------------------------------------------------------------- +struct Engine::Impl { + CoreApi api; + joc_stream* stream = nullptr; + InputFile eac3; // bare E-AC-3 input: read straight from the file + FfmpegPipe eac3_pipe; // E-AC-3 inside a container: ffmpeg extracts the stream + bool eac3_from_pipe = false; + FfmpegPipe bed; + Settings settings; + std::string input_path; + + // The metadata stream comes either from the file itself or from ffmpeg. + std::size_t read_eac3(void* destination, std::size_t bytes) { + return eac3_from_pipe ? eac3_pipe.read(destination, bytes) + : eac3.read(destination, bytes); + } + + unsigned channels = 0; + // Decoded bed channel count, resolved from joc_dmx_config_idx before the bed + // decoder starts: 6 for configurations 0/3, 8 for 1/2/4. + std::size_t bed_channels = kDefaultBedChannels; + std::uint64_t frames_queued = 0; // audio frames handed to the core + std::uint64_t bed_frames_pushed = 0; + bool eac3_eof = false; + bool bed_eof = false; + bool flushed = false; + unsigned trace_count = 0; + unsigned read_calls = 0; + std::size_t eac3_carry = 0; // trailing partial syncframe, for exact counting + std::uint64_t bed_bytes_read = 0; + std::vector eac3_buffer; + std::vector bed_buffer; + std::size_t bed_staged_bytes = 0; // bytes staged at the front of bed_buffer + std::vector pull_buffer; + + // Seek state. seek_skip counts output frames still to be discarded: a seek + // restarts the inputs on the syncframe before the target, and the samples the + // renderer produces for the part already behind the target are dropped here. + std::uint64_t seek_skip = 0; + // Delivered-stream accounting: where the stream currently being delivered starts + // on the source timeline, how much of it has been handed over, and where it has + // to stop. end_sample is the file's own end, so a binaural room tail cannot + // turn into playback time the file does not have. + std::uint64_t start_sample = 0; + std::uint64_t delivered = 0; + std::uint64_t end_sample = 0; // 0 = no limit + // Syncframes of a container's metadata stream still to be read and thrown away. + // ffmpeg's input seek on a copy stream lands on the frame whose timestamp is + // at or after the target, which is not reliably the frame the bed restarts on, + // so a container seek re-reads the stream and drops the frames here instead. + std::uint64_t metadata_skip = 0; + bool at_end = false; // seek landed at or past the end + std::function abort_check; + // Bare-stream syncframe index: offset of every syncframe within the stream + // (so index_base has to be added to get a file offset). Filled by walking the + // file, and only as far as a seek asks for. + std::vector frame_offsets; + std::uint64_t index_base = 0; // file offset the stream starts at + std::uint64_t index_file_offset = 0; // file offset the walk continues from + std::uint64_t index_stream_offset = 0; // stream offset the walk continues from + bool index_complete = false; + + void reset_feed_state() { + frames_queued = 0; + bed_frames_pushed = 0; + eac3_eof = false; + bed_eof = false; + flushed = false; + trace_count = 0; + read_calls = 0; + eac3_carry = 0; + bed_bytes_read = 0; + bed_staged_bytes = 0; + seek_skip = 0; + metadata_skip = 0; + start_sample = 0; + delivered = 0; + at_end = false; + } + + void stop_inputs() { + bed.stop(); + eac3_pipe.stop(); + eac3.close(); + } + + void reset_index() { + frame_offsets.clear(); + index_base = settings.stream_start_bytes; + index_file_offset = index_base; + index_stream_offset = 0; + index_complete = false; + } + + // Grows the syncframe index until it holds `wanted` entries or the stream ends. + bool grow_frame_index(std::uint64_t wanted, std::string* error); + // Points the file at the syncframe `frame`, or reports at_end when the stream + // has fewer frames than that. + bool position_bare(std::uint64_t frame, std::string* error); + bool start_bed(std::uint64_t source_sample, std::string* error); + bool start_metadata(std::string* error); + // Resolves bed_channels from the stream's own joc_dmx_config_idx. For a + // container this starts the metadata pipe once, reads a prefix and stops it + // again; for a bare stream it reads a prefix from the file and seeks back. + bool resolve_bed_channels(std::string* error); +}; + +bool Engine::Impl::grow_frame_index(std::uint64_t wanted, std::string* error) { + constexpr std::size_t kWindow = 256u * 1024u; + std::vector buffer(kWindow); + while (frame_offsets.size() < wanted && !index_complete) { + if (abort_check != nullptr && !abort_check()) { + if (error != nullptr) *error = "the seek was aborted"; + return false; + } + if (!eac3.is_open() && !eac3.open(input_path)) { + if (error != nullptr) *error = "cannot reopen the input file"; + return false; + } + const std::uint64_t size = eac3.size(); + if (index_file_offset + 4u > size) { + index_complete = true; + break; + } + if (!eac3.seek(index_file_offset)) { + if (error != nullptr) *error = "cannot position the input file"; + return false; + } + const std::uint64_t remaining = size - index_file_offset; + const std::size_t want = static_cast( + remaining < kWindow ? remaining : kWindow); + const std::size_t got = eac3.read(buffer.data(), want); + if (got < 4u) { + index_complete = true; + break; + } + // The index holds audio frames, not syncframes: the renderer consumes one + // bed frame per audio frame, and a 7-channel program makes two syncframes + // into one audio frame. + const bool at_end = (index_file_offset + got >= size); + std::size_t consumed = 0; + while (frame_offsets.size() < wanted) { + const std::size_t bytes = + joc_eac3::audio_frame_bytes_at(buffer.data(), got, consumed, at_end); + if (bytes == 0 || consumed + bytes > got) break; + frame_offsets.push_back(index_stream_offset + consumed); + consumed += bytes; + } + if (consumed == 0) { + // Not even one whole syncframe in a full window: the stream stops here. + index_complete = true; + break; + } + index_file_offset += consumed; + index_stream_offset += consumed; + } + return true; +} + +bool Engine::Impl::position_bare(std::uint64_t frame, std::string* error) { + if (!grow_frame_index(frame + 1u, error)) return false; + if (frame >= frame_offsets.size()) { + // Past the last syncframe: the decoder contract asks for a successful seek + // that the next read() answers with end of stream. + at_end = true; + stop_inputs(); + return true; + } + // Position check first: frame_offsets.size() is what bounds the index. + const std::uint64_t file_offset = + index_base + frame_offsets[static_cast(frame)]; + if (!eac3.is_open() && !eac3.open(input_path)) { + if (error != nullptr) *error = "cannot reopen the input file"; + return false; + } + // The renderer rejects a stream that does not begin on a syncword and never + // resynchronises, so a mispositioned start has to fail loudly here rather than + // turn into silence at the end of the file. + std::uint8_t header[8] = {}; + if (!eac3.seek(file_offset) || eac3.read(header, sizeof(header)) < 4u || + joc_eac3::frame_bytes_at(header, sizeof(header), 0) == 0) { + if (error != nullptr) { + *error = "the syncframe index does not point at a syncframe (offset " + + std::to_string(file_offset) + ")"; + } + return false; + } + if (!eac3.seek(file_offset)) { + if (error != nullptr) *error = "cannot position the input file"; + return false; + } + return true; +} + +bool Engine::Impl::resolve_bed_channels(std::string* error) { + bed_channels = kDefaultBedChannels; + std::vector buffer(1u << 20); + int config = -1; + if (eac3_from_pipe) { + // The metadata stream has to run once to be sniffed; it is stopped again and + // restarted from the beginning, which costs one extra ffmpeg spawn per track. + if (!start_metadata(error)) return false; + const std::size_t got = eac3_pipe.read(buffer.data(), buffer.size()); + eac3_pipe.stop(); + config = scan_config_idx(buffer.data(), got); + } else { + if (!eac3.is_open() && !eac3.open(input_path)) { + if (error != nullptr) *error = "cannot open the input file"; + return false; + } + const std::size_t got = eac3.read(buffer.data(), buffer.size()); + config = scan_config_idx(buffer.data(), got); + // Put the file back where the feed loop expects it. + if (!eac3.seek(index_base)) { + if (error != nullptr) *error = "cannot position the input file"; + return false; + } + } + bed_channels = seven_channel_config(config) + ? static_cast(7u + 1u) + : kDefaultBedChannels; + if (bed_channels > kMaxBedChannels) bed_channels = kMaxBedChannels; + joc_log::line("core: joc_dmx_config_idx=%d -> %llu bed channel(s)", config, + static_cast(bed_channels)); + return true; +} + +bool Engine::Impl::start_bed(std::uint64_t source_sample, std::string* error) { + // The core PCM the kernel expects: interleaved float32 at 48 kHz, laid out as + // L R C LFE Ls Rs for 5.1 and L R C LFE BL BR SL SR for 7.1. + // -drc_scale 0 -target_level 0: the bed is taken as stored, without the + // stream's dynrng or target-level metadata being applied by the decoder. + // + // -ac is only passed for the 5.1 configurations: `-ac 6` downmixes 5.1.2/7.1 + // into 5.1 and drops the extra pair, and `-ac 8` would remap 5.1.2 into 7.1. + // The 7-channel configurations take the decoder's own layout instead. + // + // -ss is an input option: the demuxer is positioned on the frame boundary and + // decoding starts there, so a seek costs the same wherever it lands. The price is + // that the bed is carried by a decoder that started at the seek point rather than + // at the start of the file, which is a low-level, noise-like difference from a + // play-through rather than a misalignment: the position stays exact. + std::wstring input_arguments = L"-drc_scale 0 -target_level 0"; + if (has_mov_timeline(input_path)) input_arguments += L" -ignore_editlist 1"; + const std::wstring offset = seek_time(source_sample); + if (!offset.empty()) input_arguments += L" -ss " + offset; + std::wstring bed_arguments = L"-map 0:a:"; + bed_arguments += std::to_wstring(settings.audio_index); + bed_arguments += L" -vn"; + if (bed_channels == kDefaultBedChannels) { + bed_arguments += L" -ac 6"; + } + bed_arguments += L" -ar 48000 -c:a pcm_f32le -f f32le -"; + return bed.start(settings.ffmpeg_path, input_path, input_arguments, bed_arguments, "bed", + stderr_path_for(L"joc_ffmpeg_bed.log"), error); +} + +bool Engine::Impl::start_metadata(std::string* error) { + // Stream copy from the start of the track: the syncframes arrive byte for byte + // as they are stored, which is what the JOC metadata needs, and a seek then + // discards whole syncframes from the front (see metadata_skip) rather than + // asking ffmpeg to position the stream. + std::wstring stream_arguments = L"-map 0:a:"; + stream_arguments += std::to_wstring(settings.audio_index); + stream_arguments += L" -vn -c:a copy -f eac3 -"; + return eac3_pipe.start(settings.ffmpeg_path, input_path, std::wstring(), stream_arguments, + "metadata", stderr_path_for(L"joc_ffmpeg_stream.log"), error, + 1u << 20); +} + +Engine::Engine() : impl_(new Impl()) {} + +Engine::~Engine() { + stop(); + delete impl_; +} + +unsigned Engine::channels() const { return impl_->channels; } + +void Engine::set_abort_check(std::function check) { impl_->abort_check = std::move(check); } + +void Engine::set_length(double seconds) { impl_->end_sample = sample_of_seconds(seconds); } + +void Engine::stop() { + Impl& impl = *impl_; + if (impl.stream != nullptr && impl.api.destroy != nullptr) { + impl.api.destroy(impl.stream); + impl.stream = nullptr; + } + impl.stop_inputs(); + impl.reset_feed_state(); +} + +bool Engine::start(const std::string& input_path, const Settings& settings, std::string* error) { + Impl& impl = *impl_; + // initialize() may be called more than once on the same instance, and each call + // has the renderer and its inputs start from scratch. + stop(); + impl.settings = settings; + impl.input_path = input_path; + impl.reset_index(); + impl.reset_feed_state(); + impl.end_sample = sample_of_seconds(settings.length_seconds); + impl.eac3_buffer.resize(kEac3Chunk); + + if (!load_api(settings.core_path, &impl.api, error)) return false; + const std::uint32_t abi = impl.api.abi_version(); + const char* version = impl.api.version_string != nullptr ? impl.api.version_string() : "?"; + joc_log::line("core: in-process renderer %s (abi %u), component built against abi %u", + version, abi, static_cast(JOC_ABI_VERSION)); + if (abi != JOC_ABI_VERSION) { + joc_log::line("core: ABI mismatch; refusing to continue"); + if (error != nullptr) *error = "the bundled renderer ABI does not match the component"; + return false; + } + + // Metadata stream: a bare E-AC-3 file is read directly, while the E-AC-3 track + // of a container is extracted by ffmpeg (stream copy, so the syncframes reach + // the renderer exactly as stored). + impl.eac3_from_pipe = (settings.input_kind == InputKind::kContainer); + if (!impl.eac3_from_pipe) { + if (!impl.eac3.open(input_path)) { + if (error != nullptr) *error = "cannot open the input file"; + return false; + } + // A tag area in front of the stream is skipped here rather than by the + // renderer, which rejects a stream that does not begin on a syncword. + if (impl.index_base != 0 && !impl.eac3.seek(impl.index_base)) { + if (error != nullptr) *error = "cannot skip the leading tag area"; + return false; + } + } + + // The bed decoder has to know how many channels to produce before it starts, + // and that comes from the stream's own joc_dmx_config_idx. + if (!impl.resolve_bed_channels(error)) return false; + impl.bed_buffer.resize(kBedFramesChunk * impl.bed_channels); + + joc_stream_config config{}; + config.struct_size = sizeof(config); + config.struct_version = 1; + config.input = JOC_STREAM_IN_EAC3; + config.output = (settings.output == Output::kBinaural) ? JOC_STREAM_OUT_BINAURAL + : JOC_STREAM_OUT_SPEAKER; + config.speaker_layout_name = settings.speaker_layout.c_str(); + config.speaker_metadata_offset = 0; + config.binaural_mode = settings.binaural_mode; + // The filter bank tables live in the library (hrtf::builtin_kernels in + // kernel_tables.cpp), so there is no table path to configure and none is + // passed: the field stays null. The same goes for the compiled-HRTF cache: + // it is the renderer's internal business, not a user choice. + config.kernels_path = nullptr; + config.hrtf_path = nullptr; + // Only binaural output reads an HRTF at all: a speaker layout must not be + // blocked by a missing HRTF file, and must not have to name one. + std::string hrtf_in_use; + if (settings.output == Output::kBinaural) { + hrtf_in_use = resolve_hrtf_file(settings); + const std::string& hrtf_file = hrtf_in_use; + if (hrtf_file.empty()) { + if (error != nullptr) { + *error = "双耳渲染需要 HRTF 文件,但组件目录无法确定;请在设置页里显式指定路径"; + } + return false; + } + if (!file_exists(hrtf_file)) { + if (error != nullptr) { + *error = std::string("找不到 HRTF 文件:") + hrtf_file + + (settings.hrtf_file.empty() ? "(默认位置,可在设置页里指定其它路径)" + : ""); + } + return false; + } + if (settings.hrtf_source == HrtfSource::kRosella) { + config.personalized_headphone_path = hrtf_file.c_str(); + } else { + config.hrtf_sofa_path = hrtf_file.c_str(); + } + } + config.hrtf_cache_policy = settings.hrtf_cache_policy; + config.hrtf_cache_dir = + settings.hrtf_cache_dir.empty() ? nullptr : settings.hrtf_cache_dir.c_str(); + config.hrtf_radius_m = settings.hrtf_radius_m; + config.binaural_tail_seconds = settings.tail_seconds; + config.object_delay_samples = settings.object_delay_samples; + config.gain_db = settings.gain_db; + config.native_threads = settings.native_threads; + + const joc_error created = impl.api.create(&config, &impl.stream); + if (created != JOC_OK) { + if (error != nullptr) { + *error = std::string("cannot create the render stream: ") + + error_with_detail(impl.api, created); + } + return false; + } + joc_stream_status_info status{}; + status.struct_size = sizeof(status); + status.struct_version = 1; + if (impl.api.status(impl.stream, &status) == JOC_OK && status.output_channels != 0u) { + impl.channels = status.output_channels; + } else { + impl.channels = (settings.output == Output::kBinaural) + ? 2u + : speaker_channels(settings.speaker_layout); + } + joc_log::line("core: stream created, %u output channel(s), layout=%s, hrtf=%s", impl.channels, + settings.speaker_layout.c_str(), + hrtf_in_use.empty() ? "(none)" : hrtf_in_use.c_str()); + + // ffmpeg's stderr lands next to the component rather than in whatever working + // directory the host process happens to have. The two children write separate + // files so neither can truncate the other's diagnostics. + if (!impl.start_bed(0, error)) return false; + if (impl.eac3_from_pipe && !impl.start_metadata(error)) return false; + return true; +} + +bool Engine::seek(double seconds, double total_seconds, std::string* error) { + Impl& impl = *impl_; + if (impl.stream == nullptr || impl.api.reset == nullptr) { + if (error != nullptr) *error = "the renderer is not running"; + return false; + } + + // Where the stream that is about to be delivered starts: + // + // * the frame the target sits in, minus a pre-roll, so the renderer's own state + // -- object timeline, matrix interpolation, room tail -- has converged by the + // time the target itself is delivered. Both inputs restart there, and the bed + // is positioned with an input seek, which is what keeps the cost of a seek + // independent of where it lands; + // * the samples in front of the target are then dropped from the output, which is + // what makes the delivery start exactly on the requested sample. + const std::int64_t target = sample_of_seconds(seconds); + std::int64_t wanted = target - static_cast(impl.settings.pipeline_delay_samples); + if (wanted < 0) wanted = 0; + const std::uint64_t target_frame = static_cast(wanted) / kFrameSamples; + const std::uint64_t preroll = impl.settings.seek_preroll_frames; + const std::uint64_t frame = (target_frame > preroll) ? (target_frame - preroll) : 0; + const std::uint64_t first_sample = frame * kFrameSamples; + const std::uint64_t skip = static_cast(wanted) - first_sample; + + impl.stop_inputs(); + impl.reset_feed_state(); + + if (impl.eac3_from_pipe) { + // A container's frame count is not known before it is decoded, so the + // caller's duration is what says whether this lands past the end. + if (total_seconds > 0.0 && seconds >= total_seconds) { + impl.at_end = true; + joc_log::line("engine: seek %.6f s is at or past the end (%.6f s)", seconds, + total_seconds); + } + } else if (!impl.position_bare(frame, error)) { + return false; + } + + if (!impl.at_end) { + if (!impl.start_bed(first_sample, error)) return false; + if (impl.eac3_from_pipe) { + if (!impl.start_metadata(error)) return false; + impl.metadata_skip = frame; + } + impl.seek_skip = skip; + impl.start_sample = static_cast(wanted); + impl.delivered = 0; + } + + // joc_stream_reset keeps the renderer and its HRTF field: it drops the whole + // timeline, gain ramps, room tail and filter-bank history, which is exactly + // what a restart at another position needs. + const joc_error reset = impl.api.reset(impl.stream); + if (reset != JOC_OK) { + if (error != nullptr) { + *error = std::string("cannot reset the render stream: ") + + error_with_detail(impl.api, reset); + } + return false; + } + joc_log::line("engine: seek %.6f s -> source sample %lld, frames %llu.. from sample %llu, " + "drop %llu sample(s)%s", + seconds, static_cast(target), + static_cast(frame), + static_cast(first_sample), + static_cast(impl.seek_skip), + impl.at_end ? " (at end)" : ""); + return true; +} + +std::size_t Engine::read(float* destination, std::size_t frames, std::string* error) { + Impl& impl = *impl_; + if (impl.stream == nullptr || frames == 0) return 0; + // A seek at or past the end of the file succeeds and leaves the next read to + // report end of stream. + if (impl.at_end) return 0; + const bool trace = impl.trace_count < 6; + ++impl.read_calls; + if ((impl.read_calls % 50u) == 0u) { + joc_log::line("engine: call %u queued=%llu bed=%llu staged_bytes=%llu eac3_eof=%d bed_eof=%d flushed=%d", + impl.read_calls, static_cast(impl.frames_queued), + static_cast(impl.bed_frames_pushed), + static_cast(impl.bed_staged_bytes), impl.eac3_eof ? 1 : 0, + impl.bed_eof ? 1 : 0, impl.flushed ? 1 : 0); + } + + for (;;) { + if (trace) { + joc_log::line("engine: loop eac3_eof=%d bed_eof=%d queued=%llu bed=%llu staged_bytes=%llu", + impl.eac3_eof ? 1 : 0, impl.bed_eof ? 1 : 0, + static_cast(impl.frames_queued), + static_cast(impl.bed_frames_pushed), + static_cast(impl.bed_staged_bytes)); + } + // Feed the metadata stream, keeping it only a little ahead of the bed so + // the core's pairing queue stays small. + // A test-side input limit has to look like end of file, or the loop below + // never reaches its terminal state. + if (impl.settings.input_frame_limit != 0 && + impl.frames_queued >= impl.settings.input_frame_limit) { + impl.eac3_eof = true; + } + + // Queue more input only while less than one read's worth is waiting. + std::size_t rendered_ahead = 0; + { + joc_stream_status_info pending{}; + pending.struct_size = sizeof(pending); + pending.struct_version = 1; + if (impl.api.status(impl.stream, &pending) == JOC_OK) { + rendered_ahead = static_cast(pending.buffered_samples); + } + } + + if (!impl.eac3_eof && rendered_ahead < kMaxRenderedAheadSamples && + impl.frames_queued <= impl.bed_frames_pushed + 2u && + (impl.settings.input_frame_limit == 0 || + impl.frames_queued < impl.settings.input_frame_limit)) { + // The tail of a chunk is usually the head of the next syncframe. It + // stays at the front of the buffer so the frame count stays exact + // across chunk boundaries: counting each chunk on its own loses one + // frame at the end, which leaves the bed a frame short and the last + // frame of the file unrendered. + const std::size_t got = impl.read_eac3(impl.eac3_buffer.data() + impl.eac3_carry, + impl.eac3_buffer.size() - impl.eac3_carry); + std::size_t total = impl.eac3_carry + got; + // A read that returns nothing means no more bytes will arrive, so the + // audio frame still open in the buffer is complete by definition. Without + // this the last audio frame of every file is left in the carry. + const bool at_eof = (got == 0) || impl.eac3_eof; + if (total == 0) { + impl.eac3_eof = true; + } else { + // Syncframes in front of a seek target are thrown away before + // anything is interpreted. They are dropped a whole window at a + // time, so only as much of the stream is read as the skip needs. + if (impl.metadata_skip != 0) { + std::size_t dropped = 0; + while (impl.metadata_skip != 0) { + const std::size_t bytes = joc_eac3::audio_frame_bytes_at( + impl.eac3_buffer.data(), total, dropped, at_eof); + if (bytes == 0 || dropped + bytes > total) break; + dropped += bytes; + --impl.metadata_skip; + } + if (dropped != 0) { + total -= dropped; + std::memmove(impl.eac3_buffer.data(), + impl.eac3_buffer.data() + dropped, total); + } + if (impl.metadata_skip != 0) { + // The window ended inside the part to be skipped: keep what + // is left and come back with the next read. + impl.eac3_carry = total; + if (got == 0) impl.eac3_eof = true; + continue; + } + } + + std::size_t offset = 0; + std::uint64_t complete = 0; + while (true) { + const std::size_t bytes = joc_eac3::audio_frame_bytes_at( + impl.eac3_buffer.data(), total, offset, at_eof); + if (bytes == 0 || offset + bytes > total) break; + offset += bytes; + ++complete; + } + // Both cuts land on a frame boundary because the renderer's output + // depends on how many frames it was given: the input limit has to + // stop where it says, and a read queues only its own budget. + std::uint64_t allowed = complete; + if (impl.settings.input_frame_limit != 0) { + const std::uint64_t room = + impl.settings.input_frame_limit - impl.frames_queued; + if (allowed > room) allowed = room; + } + if (allowed > kEac3FramesPerRead) allowed = kEac3FramesPerRead; + std::size_t push_bytes = offset; + std::uint64_t pushed_frames = complete; + if (allowed < complete) { + pushed_frames = allowed; + std::size_t walk = 0; + for (std::uint64_t index = 0; index < pushed_frames; ++index) { + const std::size_t bytes = joc_eac3::audio_frame_bytes_at( + impl.eac3_buffer.data(), total, walk, at_eof); + if (bytes == 0 || walk + bytes > total) break; + walk += bytes; + } + push_bytes = walk; + } + joc_stream_buffer input{}; + input.struct_size = sizeof(input); + input.struct_version = 1; + input.kind = JOC_STREAM_IN_EAC3; + input.bytes = impl.eac3_buffer.data(); + input.byte_count = static_cast(push_bytes); + const joc_error pushed = impl.api.push(impl.stream, &input, nullptr, nullptr); + if (pushed != JOC_OK) { + if (error != nullptr) { + *error = std::string("E-AC-3 push failed: ") + + error_with_detail(impl.api, pushed); + } + return 0; + } + impl.frames_queued += pushed_frames; + impl.eac3_carry = total - push_bytes; + if (impl.eac3_carry != 0 && push_bytes != 0) { + std::memmove(impl.eac3_buffer.data(), impl.eac3_buffer.data() + push_bytes, + impl.eac3_carry); + } + // The pipe can end with complete syncframes still buffered; they + // are queued next, so end of input is only real once none remain. + if (got == 0 && pushed_frames >= complete) impl.eac3_eof = true; + } + } + + // Feed the core PCM until the bed has caught up with the metadata. The + // core pairs one syncframe with exactly 1536 bed samples, so only whole + // frames are pushed; whatever is left over stays at the front of the + // staging buffer. Staging counted in bytes, not samples: a pipe read may + // return any number of bytes, and rounding a read down to whole samples + // quietly drops the rest of the stream's alignment. + while (!impl.bed_eof && impl.bed_frames_pushed < impl.frames_queued) { + const std::size_t frame_bytes = kFrameSamples * impl.bed_channels * sizeof(float); + const std::size_t whole_frames = impl.bed_staged_bytes / frame_bytes; + if (whole_frames != 0) { + joc_stream_buffer input{}; + input.struct_size = sizeof(input); + input.struct_version = 1; + input.kind = JOC_STREAM_IN_CORE_PCM; + input.pcm = impl.bed_buffer.data(); + input.channels = static_cast(impl.bed_channels); + input.sample_rate = 48000; + input.sample_count = static_cast(whole_frames * kFrameSamples); + const joc_error pushed = impl.api.push(impl.stream, &input, nullptr, nullptr); + if (pushed != JOC_OK) { + if (error != nullptr) { + *error = std::string("core PCM push failed: ") + + error_with_detail(impl.api, pushed); + } + return 0; + } + impl.bed_frames_pushed += whole_frames; + const std::size_t pushed_bytes = whole_frames * frame_bytes; + impl.bed_staged_bytes -= pushed_bytes; + if (impl.bed_staged_bytes != 0) { + std::memmove(impl.bed_buffer.data(), + reinterpret_cast(impl.bed_buffer.data()) + + pushed_bytes, + impl.bed_staged_bytes); + } + continue; + } + + // Less than one whole frame staged: read more. + const std::size_t capacity_bytes = impl.bed_buffer.size() * sizeof(float); + const std::size_t room = capacity_bytes - impl.bed_staged_bytes; + const std::size_t want = + (room < kBedReadBytes) ? room : kBedReadBytes; + if (want == 0) break; // cannot happen while capacity exceeds a frame + const std::size_t bytes = impl.bed.read( + reinterpret_cast(impl.bed_buffer.data()) + impl.bed_staged_bytes, + want); + if (bytes == 0) { + impl.bed_eof = true; + break; + } + impl.bed_bytes_read += bytes; + impl.bed_staged_bytes += bytes; + } + + // Take whatever the renderer has. + joc_stream_buffer output{}; + output.struct_size = sizeof(output); + output.struct_version = 1; + output.kind = (impl.settings.output == Output::kBinaural) ? JOC_STREAM_OUT_BINAURAL + : JOC_STREAM_OUT_SPEAKER; + output.channels = impl.channels; + output.sample_rate = 48000; + output.sample_count = static_cast(frames); + output.out_pcm = destination; + std::uint32_t produced = 0; + const joc_error pulled = impl.api.pull(impl.stream, &output, &produced); + if (pulled != JOC_OK) { + if (error != nullptr) { + *error = std::string("pull failed: ") + error_with_detail(impl.api, pulled); + } + return 0; + } + if (produced != 0u) { + std::size_t count = produced; + if (impl.seek_skip != 0) { + // The renderer had to be fed from before the seek target, so the + // samples it produces for that part are dropped before anything + // reaches the caller: the first sample handed over is the target. + const std::size_t drop = (impl.seek_skip < count) + ? static_cast(impl.seek_skip) + : count; + impl.seek_skip -= drop; + count -= drop; + if (count != 0) { + std::memmove(destination, destination + drop * impl.channels, + count * impl.channels * sizeof(float)); + } + if (count == 0) continue; // the whole pull was pre-roll + } + // The renderer's binaural room tail is not part of the file: the stream + // ends where the file ends, not later. + if (impl.end_sample != 0) { + const std::uint64_t from = impl.start_sample + impl.delivered; + if (from >= impl.end_sample) return 0; + const std::uint64_t left = impl.end_sample - from; + if (left < count) count = static_cast(left); + } + impl.delivered += count; + if (trace) { + ++impl.trace_count; + joc_log::line("engine: pulled %u frame(s) on the %u%s attempt", count, + impl.trace_count, impl.trace_count == 1 ? "st" : "th"); + } + return count; + } + + // Nothing more can arrive once the metadata stream is drained and the bed + // has caught up with it. The bed process is normally stopped as a + // consequence of that catch-up rather than by reaching its own end, so + // waiting for bed_eof here would spin forever. + const bool no_more_input = + impl.eac3_eof && + (impl.bed_eof || impl.bed_frames_pushed >= impl.frames_queued); + if (no_more_input) { + if (!impl.flushed) { + const joc_error flushed = impl.api.flush(impl.stream); + if (flushed != JOC_OK) { + if (error != nullptr) { + *error = std::string("flush failed: ") + error_with_detail(impl.api, flushed); + } + return 0; + } + impl.flushed = true; + joc_stream_status_info status{}; + status.struct_size = sizeof(status); + status.struct_version = 1; + if (impl.api.status(impl.stream, &status) == JOC_OK) { + joc_log::line( + "core: exhausted (eac3 frames queued=%llu, bed frames pushed=%llu); " + "core counters frames_in=%llu frames_out=%llu samples_out=%llu " + "buffered=%llu", + static_cast(impl.frames_queued), + static_cast(impl.bed_frames_pushed), + static_cast(status.frames_in), + static_cast(status.frames_out), + static_cast(status.samples_out), + static_cast(status.buffered_samples)); + // Metadata the renderer had to work around; each one is per audio + // frame and a non-zero count is worth reporting with the rest. + if (status.missing_joc_frames != 0u || status.objects_clamped_frames != 0u || + status.extra_container_frames != 0u || + status.chanmap_pair_mismatch_frames != 0u || + status.bed_mask_mismatch_frames != 0u) { + joc_log::line( + "core: metadata workarounds: missing_joc_frames=%llu " + "objects_clamped_frames=%llu extra_container_frames=%llu " + "chanmap_pair_mismatch_frames=%llu bed_mask_mismatch_frames=%llu", + static_cast(status.missing_joc_frames), + static_cast(status.objects_clamped_frames), + static_cast(status.extra_container_frames), + static_cast(status.chanmap_pair_mismatch_frames), + static_cast(status.bed_mask_mismatch_frames)); + } + joc_log::line("core: bed bytes read=%llu, staged samples left=%llu", + static_cast(impl.bed_bytes_read), + static_cast(impl.bed_staged_bytes)); + } + continue; // drain the tail + } + return 0; // genuinely done + } + } +} + +} // namespace joc_decode diff --git a/src/joc_decode.h b/src/joc_decode.h new file mode 100644 index 0000000..5181878 --- /dev/null +++ b/src/joc_decode.h @@ -0,0 +1,206 @@ +// Decode engine: E-AC-3 JOC file -> rendered PCM, without any host-specific types. +// +// Kept free of fb2k headers on purpose: the same code is what a headless harness +// drives when the output has to be compared byte for byte against joc_cli. +// +// Two inputs are needed to render, and they come from different places: +// * the E-AC-3 syncframes -- the metadata stream -- read straight from the file; +// * the 5.1 core PCM of those same frames -- the rendering core does not decode +// the core (it has no AC-3 decoder at all), so ffmpeg produces it. +// +// The core is the C++ kernel under kernel/, compiled into this component and called +// through its public C API via the CoreApi table. No DLL is shipped or loaded: the +// table is filled with the linked entry points and start-up only checks the ABI +// version. +#pragma once + +#include +#include +#include +#include + +namespace joc_decode { + +// Delay of the rendering pipeline itself, in output samples: in a run that began +// at source sample 0, output sample k carries the rendering of source sample +// k - this value. A seek starts the inputs this much earlier and drops the +// samples before the target. Measured as 0: the renderer's own filter-bank +// latency and its metadata delay are inside the renderer, not delays of the +// delivered stream. It stays a named, overridable constant so the measurement can +// be repeated. +constexpr std::uint32_t kJocSeekPipelineDelaySamples = 0; + +// Syncframes fed before the frame the target sits in. The renderer's state is +// rebuilt from the frames it is given, so a restart needs a moment to converge and +// the delivered part has to be past that. Two things converge at different rates: +// the metadata state (object positions, matrix interpolation, gain ramps), which +// the measured 3008-sample window covers, and the binaural room tail, which is +// recursive and can only be approached -- two syncframes are enough for the speaker +// path, and the tail keeps improving with more, which is why this is 64. +constexpr std::uint32_t kJocSeekPrerollFrames = 64; + +enum class Output { + kBinaural = 0, // 2 channels, HRTF rendering + kSpeaker = 1, // N channels, named layout +}; + +// Which HRTF to render with. Both inputs are user-facing model/data files; how +// the renderer gets from them to its internal filter field is its own business. +enum class HrtfSource { + kSofa = 0, + kRosella = 1, +}; + +// Where the E-AC-3 syncframes come from. A bare stream is read straight from the +// file; inside a container the track has to be extracted first (ffmpeg, stream copy). +enum class InputKind { + kBare = 0, + kContainer = 1, +}; + +struct Settings { + Output output = Output::kBinaural; + InputKind input_kind = InputKind::kBare; + // Which of the container's audio tracks holds the E-AC-3 stream, 0-based. + unsigned audio_index = 0; + std::string speaker_layout = "7.1"; + HrtfSource hrtf_source = HrtfSource::kSofa; + // Empty means the default file in the default folder, see resolve_hrtf_file(). + std::string hrtf_file; + std::string hrtf_cache_dir; // SOFA compile cache (disk policy) + unsigned hrtf_cache_policy = 1; // 0 none, 1 memory, 2 disk + double hrtf_radius_m = 1.0; // SOFA measurement-radius shell + std::uint32_t binaural_mode = 3; // JOC_BINAURAL_MID + double gain_db = 0.0; + double tail_seconds = 5.0; + // Duration of the file, in seconds. The renderer ends a binaural stream with a + // room tail, which would be played as time the file does not have; the delivered + // stream is cut at exactly this much audio instead. Zero means "no limit". + double length_seconds = 0.0; + std::uint32_t object_delay_samples = 1473; + std::uint32_t native_threads = 0; + std::string ffmpeg_path = "ffmpeg"; + // Where joc_core.dll lives; empty means the renderer's default lookup + // (the plugin's own directory first). + std::string core_path; + // Bytes in front of the first syncframe -- a leading ID3v2 tag. The renderer + // rejects a stream that does not begin on a syncword, so both the walk and the + // feed start here. + std::uint64_t stream_start_bytes = 0; + // Samples of pipeline delay a seek compensates for, and syncframes it pre-rolls + // before the target: the calibrated constants above, unless the comparison + // harness overrides them to measure those constants. + std::uint32_t pipeline_delay_samples = kJocSeekPipelineDelaySamples; + std::uint32_t seek_preroll_frames = kJocSeekPrerollFrames; + // Stop feeding the renderer after this many input syncframes and flush, which + // is what the reference CLI's --duration does. Zero means "the whole file". + // Only the comparison harness sets it; playback leaves it at zero. + std::uint64_t input_frame_limit = 0; + // Deliver 24-bit fixed-point PCM instead of float32. The renderer itself is + // always float32 and this does not change it: the flag says how the *caller* + // hands the samples on, and the quantisation happens once, where the format is + // decided (see pack_int24 below). It exists because the streaming interface + // has no int24 output -- the core's int24 rule lives in its file-writing path + // (kernel/src/io/wav_writer.cpp), which the component cannot reach, so the + // rule is reproduced here instead. Out-of-range samples follow the core's + // JOC_CLIP_CONTINUE policy: truncated to the edge, and reported. + bool force_int24 = false; +}; + +// Channel count of a named layout, or 0 when the layout is not one of the +// layouts the core accepts. +unsigned speaker_channels(const std::string& layout); + +// Directory this component's DLL was loaded from. The default HRTF folder is +// \HRTF, the same place the reference CLI looks next to its exe. +std::string component_directory(); + +// The HRTF file a configuration will actually use: the configured path, or the +// default file in the default folder when none is configured. Empty when the +// component directory cannot be determined. +std::string resolve_hrtf_file(const Settings& settings); + +// Every layout the core accepts, in the order a settings page should list them. +const char* const* speaker_layouts(std::size_t* count); + +// Result of examining a file without rendering anything. +struct FileProbe { + bool readable = false; + bool joc = false; // every examined syncframe carries JOC + std::uint32_t sample_rate = 0; + std::uint32_t channels = 0; // core 5.1 layout, i.e. 6 (including LFE) + std::uint64_t frames = 0; // E-AC-3 syncframes in the file + double duration_seconds = 0.0; + std::string detail; +}; + +// Walks the file's syncframes. Cheap enough for a Media Library scan: it only +// does pointer arithmetic over the stream, no decoding, no HRTF work. The walk +// starts at `start_offset`, which is where the stream begins behind a tag area. +FileProbe probe_file(const std::string& path, std::size_t max_scan_bytes = 0, + std::uint64_t start_offset = 0); + +// Decides whether the E-AC-3 track of a container file carries JOC, without +// rendering anything: ffmpeg copies a short prefix of that track out (stream copy, +// so the syncframes are the stored ones) and the same bitstream test is applied. +// The verdict is cached per file, because the information and the decode pass would +// otherwise each launch ffmpeg for it. +bool probe_container_joc(const std::string& ffmpeg_path, const std::string& path, + unsigned audio_index, bool* joc, std::string* detail); + +// ---- forced int24 delivery ------------------------------------------------ +// +// The core's own int24 rule, reproduced byte for byte from +// kernel/src/io/wav_writer.cpp: clip to [-1, 1], multiply by 8388607, truncate +// toward zero (the core's comment: the int32 conversion is "identical to NumPy's +// float32 -> int32 cast after clipping"), write the low three bytes, little +// endian; a non-finite sample becomes 0, exactly as the core writes it. +// +// Sample values that have been through this are what a 24-bit host import +// gives back, i.e. n / 2^23. That is the scale +// a caller should use when it wants to check what the host received. +constexpr double kInt24ImportScale = 8388608.0; + +struct Int24Block { + std::size_t clipped = 0; // samples that were outside [-1, 1] + std::int32_t peak = 0; // largest magnitude actually written +}; + +// Packs `count` interleaved float32 samples into `out`, which must hold +// count * 3 bytes, and reports what the clip caught. +Int24Block pack_int24(const float* interleaved, std::size_t count, std::uint8_t* out); + +class Engine { +public: + Engine(); + ~Engine(); + Engine(const Engine&) = delete; + Engine& operator=(const Engine&) = delete; + + bool start(const std::string& input_path, const Settings& settings, std::string* error); + // Interleaved float32; returns frames produced per channel, 0 means end of stream. + std::size_t read(float* destination, std::size_t frames, std::string* error); + unsigned channels() const; + void stop(); + + // Duration of the file, in seconds, for a caller that learns it after start() + // (reported duration of the track); zero means "no limit". + void set_length(double seconds); + + // Repositions so that the next sample read() returns is the rendering of source + // sample round(seconds * 48000): the inputs restart at the syncframe holding + // that sample and the output before it is dropped. Seeking at or past + // `total_seconds` (0 when the duration is unknown) succeeds and makes the next + // read() return 0, as the decoder contract requires. start() must have run. + bool seek(double seconds, double total_seconds, std::string* error); + + // Polled while the syncframe index is being walked, so a long seek stays + // interruptible; returning false aborts the seek. + void set_abort_check(std::function check); + +private: + struct Impl; + Impl* impl_; +}; + +} // namespace joc_decode diff --git a/src/log.cpp b/src/log.cpp new file mode 100644 index 0000000..918e5d2 --- /dev/null +++ b/src/log.cpp @@ -0,0 +1,169 @@ +#include "log.h" + +#include + +#include +#include +#include +#include +#include + +#include "win_path.h" + +namespace joc_log { +namespace { + +std::mutex g_mutex; +FILE* g_file = nullptr; +bool g_opened = false; +std::string g_path; // UTF-8, for reporting +std::wstring g_wide_path; // for _wfopen +std::wstring g_wide_rolled; // g_wide_path with the .1 suffix +unsigned long long g_bytes = 0; + +// A Media Library scan calls into us for every file it walks, so the cap has to +// be on bytes: the lines a scan produces run from 40 to 2048 bytes each, and a +// cap on their number leaves the file they build unpredictable by a factor of +// fifty. Sixteen mebibytes per file, one previous file kept, so the component +// never holds more than 32 MiB of log. +constexpr unsigned long long kMaxBytes = 16ull << 20; + +// The lines recorded between header_begin() and header_end(): the version +// banner, a handful of lines written once per process. +bool g_recording = false; +std::string g_header; + +std::wstring module_directory() { + HMODULE module = nullptr; + if (!GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS | + GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, + reinterpret_cast(&module_directory), &module)) { + return {}; + } + wchar_t buffer[4096] = {}; + const DWORD length = GetModuleFileNameW(module, buffer, static_cast(4096)); + if (length == 0) return {}; + std::wstring dir(buffer, length); + const std::wstring::size_type slash = dir.find_last_of(L"\\/"); + if (slash != std::wstring::npos) dir.resize(slash); + return dir; +} + +void open_locked() { + g_opened = true; + + wchar_t from_env[4096] = {}; + const DWORD env_length = GetEnvironmentVariableW(L"JOC_LOG", from_env, + static_cast(4096)); + std::wstring plain; + if (env_length > 0 && env_length < 4096) { + plain.assign(from_env, env_length); + } else { + const std::wstring dir = module_directory(); + if (dir.empty()) return; + plain = dir + L"\\joc_decoder.log"; + } + + // g_path is the one the component reports and a user reads; the handles work on + // the extended form, because a portable install can sit deeper than MAX_PATH. + g_path = joc_path::to_utf8(plain); + g_wide_path = joc_path::to_wide_extended(plain); + g_wide_rolled = g_wide_path + L".1"; + g_file = _wfopen(g_wide_path.c_str(), L"wb"); + if (g_file == nullptr) { + g_path.clear(); + return; + } + // Unbuffered: the log stays readable while the process is running. + std::setvbuf(g_file, nullptr, _IONBF, 0); +} + +// Composes one line with its timestamp, writes it, and accounts for it. Returns +// the bytes written, 0 when there was nowhere to write them. +unsigned long long write_locked(const char* text) { + if (g_file == nullptr) return 0; + + SYSTEMTIME now; + GetLocalTime(&now); + char composed[2100]; + const int length = + std::snprintf(composed, sizeof(composed), "%02u:%02u:%02u.%03u [t%05lu] %s\n", now.wHour, + now.wMinute, now.wSecond, now.wMilliseconds, + static_cast(GetCurrentThreadId()), text); + if (length <= 0) return 0; + // snprintf reports the length it would have needed, which for a truncated + // line is past the end of the buffer. + const std::size_t size = (static_cast(length) < sizeof(composed)) + ? static_cast(length) + : sizeof(composed) - 1; + std::fwrite(composed, 1, size, g_file); + g_bytes += size; + if (g_recording) g_header.append(composed, size); + return size; +} + +// Moves the full file aside and starts an empty one. Called with the mutex held, +// once the budget is spent. The banner is written again afterwards, so a log +// that has rolled still opens with the versions it was produced by. +void roll_locked() { + std::fclose(g_file); + g_file = nullptr; + // One previous window, replaced rather than chained: a chain of rolls would + // be the same unbounded log under another name. A move that fails -- the .1 + // file held open by a reader -- leaves the truncation below to bound the file + // anyway, at the cost of the window that would have been kept. + MoveFileExW(g_wide_path.c_str(), g_wide_rolled.c_str(), MOVEFILE_REPLACE_EXISTING); + g_file = _wfopen(g_wide_path.c_str(), L"wb"); + if (g_file == nullptr) return; + std::setvbuf(g_file, nullptr, _IONBF, 0); + g_bytes = 0; + write_locked("[log rolled: the previous window is in the .1 file beside this one]"); + if (!g_header.empty()) { + std::fwrite(g_header.c_str(), 1, g_header.size(), g_file); + g_bytes += g_header.size(); + } +} + +} // namespace + +void open() { + std::lock_guard guard(g_mutex); + if (!g_opened) open_locked(); +} + +const char* path() { + std::lock_guard guard(g_mutex); + return g_path.c_str(); +} + +unsigned long long budget_bytes() { return kMaxBytes; } + +void line_v(const char* fmt, va_list args) { + char text[2048]; + std::vsnprintf(text, sizeof(text), fmt, args); + + std::lock_guard guard(g_mutex); + if (!g_opened) open_locked(); + if (g_file == nullptr) return; + if (write_locked(text) != 0 && g_bytes >= kMaxBytes) roll_locked(); +} + +void line(const char* fmt, ...) { + va_list args; + va_start(args, fmt); + line_v(fmt, args); + va_end(args); +} + +void header_begin() { + std::lock_guard guard(g_mutex); + g_header.clear(); + g_recording = true; +} + +void header_end() { + std::lock_guard guard(g_mutex); + g_recording = false; +} + +} // namespace joc_log diff --git a/src/log.h b/src/log.h new file mode 100644 index 0000000..eb21ba5 --- /dev/null +++ b/src/log.h @@ -0,0 +1,46 @@ +// Line-oriented diagnostic log for the component. +// +// Deliberately free of SDK/PFC dependencies so it can be reused by the offline +// harness and so that it is safe to call from any thread the core queries us on. +// +// Path: %JOC_LOG% if set, otherwise \joc_decoder.log. +// The file is truncated once per process, unbuffered, and every line is written +// straight out so the log can be read while the host is still running. +// +// Size: what is bounded is bytes, not lines. A line is anywhere between 40 and +// 2048 bytes, so a cap on the number of lines leaves the size of the file +// unpredictable by a factor of fifty. A file that reaches budget_bytes() is +// moved to .1 -- replacing any previous roll, so there is never a chain of +// them -- and a fresh one is started. Two files of the budget is therefore the +// most the component ever holds, and the newest lines are always the ones in +// . Lines written between header_begin() and header_end() are written +// again at the top of every window, so a rolled log still says which build +// produced it. +#pragma once + +#include + +namespace joc_log { + +// Opens (truncating) the log. Called lazily by line(); call it explicitly to +// get the banner before anything else in the process logs. +void open(); + +// Absolute path of the log file, or "" when it could not be opened. +const char* path(); + +// Bytes one file holds before it is rolled to .1. +unsigned long long budget_bytes(); + +// printf-style, thread safe, appends one line. +void line(const char* fmt, ...); + +// The va_list form, for a wrapper that forwards its own arguments. +void line_v(const char* fmt, va_list args); + +// Remembers the lines written in between and writes them again after every roll. +// Meant for the version banner: a handful of lines, written once. +void header_begin(); +void header_end(); + +} // namespace joc_log diff --git a/src/plugin/audio_source.cpp b/src/plugin/audio_source.cpp new file mode 100644 index 0000000..f913cb1 --- /dev/null +++ b/src/plugin/audio_source.cpp @@ -0,0 +1,130 @@ +#include "audio_source.h" + +#include +#include +#include + +#include "log.h" + +namespace joc_mpv { +namespace { +constexpr std::size_t kBlockFrames = 1536; // one E-AC-3 frame +} + +Source::Source() = default; + +Source::~Source() { close(); } + +bool Source::open(const std::string& path, const joc_decode::Settings& settings, + double duration_seconds, std::string* error) { + close(); + std::lock_guard guard(mutex_); + int24_ = settings.force_int24; + duration_ = duration_seconds; + if (!(duration_ > 0.0)) { + if (error != nullptr) *error = "the input duration is unknown"; + return false; + } + if (!engine_.start(path, settings, error)) { + engine_.stop(); + return false; + } + channels_ = engine_.channels(); + if (channels_ == 0) { + if (error != nullptr) *error = "the renderer produced no output channels"; + engine_.stop(); + return false; + } + total_samples_ = static_cast(std::llround(duration_ * 48000.0)); + produced_bytes_ = 0; + carry_.clear(); + skip_bytes_ = 0; + block_.assign(kBlockFrames * channels_, 0.0f); + if (int24_) packed_.assign(kBlockFrames * channels_ * 3u, 0); + open_ = true; + return true; +} + +void Source::close() { + std::lock_guard guard(mutex_); + if (open_) engine_.stop(); + open_ = false; + channels_ = 0; + total_samples_ = 0; + produced_bytes_ = 0; + carry_.clear(); + skip_bytes_ = 0; +} + +std::size_t Source::read(std::uint64_t data_byte_offset, std::uint8_t* out, std::size_t count, + std::string* error) { + std::lock_guard guard(mutex_); + if (!open_) { + if (error != nullptr) *error = "the renderer is not running"; + return 0; + } + const std::uint64_t total = data_bytes(); + if (data_byte_offset >= total) return 0; + count = static_cast(std::min(count, total - data_byte_offset)); + + const unsigned frame_bytes = bytes_per_frame(); + // What the renderer has produced but the caller has not taken yet. + const std::uint64_t deliverable = produced_bytes_ - carry_.size(); + if (data_byte_offset != deliverable) { + const std::uint64_t sample = data_byte_offset / frame_bytes; + const std::size_t intra = static_cast(data_byte_offset % frame_bytes); + joc_log::line("source: reposition to sample %llu (was byte %llu, byte %llu)", + static_cast(sample), + static_cast(deliverable), + static_cast(data_byte_offset)); + if (!engine_.seek(static_cast(sample) / 48000.0, duration_, error)) return 0; + produced_bytes_ = sample * frame_bytes; + carry_.clear(); + skip_bytes_ = intra; + } + + std::size_t written = 0; + // Leftovers from an earlier block come first: a block is a whole number of + // frames and the caller may have asked for a smaller piece. + if (!carry_.empty()) { + const std::size_t take = std::min(count, carry_.size()); + std::memcpy(out, carry_.data(), take); + carry_.erase(carry_.begin(), carry_.begin() + static_cast(take)); + written += take; + } + while (written < count) { + const std::uint64_t remaining_samples = total_samples_ - produced_bytes_ / frame_bytes; + if (remaining_samples == 0) break; + const std::size_t want = + static_cast(std::min(kBlockFrames, remaining_samples)); + const std::size_t got = engine_.read(block_.data(), want, error); + if (got == 0) break; + produced_bytes_ += static_cast(got) * frame_bytes; + + std::size_t produced = 0; + const std::uint8_t* source = nullptr; + if (int24_) { + joc_decode::pack_int24(block_.data(), got * channels_, packed_.data()); + produced = got * channels_ * 3u; + source = packed_.data(); + } else { + produced = got * channels_ * sizeof(float); + source = reinterpret_cast(block_.data()); + } + std::size_t skip = 0; + if (skip_bytes_ != 0) { + skip = std::min(skip_bytes_, produced); + skip_bytes_ -= skip; + } + const std::size_t available = produced - skip; + const std::size_t take = std::min(count - written, available); + std::memcpy(out + written, source + skip, take); + written += take; + if (take < available) { + carry_.assign(source + skip + take, source + produced); + } + } + return written; +} + +} // namespace joc_mpv diff --git a/src/plugin/audio_source.h b/src/plugin/audio_source.h new file mode 100644 index 0000000..8716cb2 --- /dev/null +++ b/src/plugin/audio_source.h @@ -0,0 +1,58 @@ +#pragma once + +#include +#include +#include +#include + +#include "joc_decode.h" + +namespace joc_mpv { + +// Rendered audio as a seekable byte stream: the HTTP server asks for a byte +// range of the WAV data chunk, this maps it to a sample index, repositions the +// engine when the request does not continue where the last one stopped, and +// returns the requested bytes. +class Source { +public: + Source(); + ~Source(); + Source(const Source&) = delete; + Source& operator=(const Source&) = delete; + + bool open(const std::string& path, const joc_decode::Settings& settings, double duration_seconds, + std::string* error); + void close(); + + unsigned channels() const { return channels_; } + unsigned bits_per_sample() const { return int24_ ? 24u : 32u; } + unsigned bytes_per_frame() const { return channels_ * (bits_per_sample() / 8u); } + std::uint64_t total_samples() const { return total_samples_; } + std::uint64_t data_bytes() const { return total_samples_ * bytes_per_frame(); } + double duration_seconds() const { return duration_; } + + // Fills up to count bytes of the data chunk starting at data_byte_offset. + std::size_t read(std::uint64_t data_byte_offset, std::uint8_t* out, std::size_t count, + std::string* error); + +private: + std::mutex mutex_; + joc_decode::Engine engine_; + bool open_ = false; + bool int24_ = false; + unsigned channels_ = 0; + double duration_ = 0.0; + std::uint64_t total_samples_ = 0; + // Bytes the renderer has produced since the last reposition, counted from + // the start of the data chunk. Tracking bytes rather than samples keeps a + // request that starts inside a frame from forcing a reposition on every + // following read. + std::uint64_t produced_bytes_ = 0; + // Bytes produced by the renderer that the caller did not ask for yet. + std::vector carry_; + std::size_t skip_bytes_ = 0; + std::vector block_; + std::vector packed_; +}; + +} // namespace joc_mpv diff --git a/src/plugin/config.cpp b/src/plugin/config.cpp new file mode 100644 index 0000000..bfc0e3c --- /dev/null +++ b/src/plugin/config.cpp @@ -0,0 +1,150 @@ +#include "config.h" + +#include +#include +#include +#include + +namespace joc_mpv { +namespace { + +std::string trim(const std::string& value) { + std::size_t first = 0; + std::size_t last = value.size(); + while (first < last && (value[first] == ' ' || value[first] == '\t')) ++first; + while (last > first && (value[last - 1] == ' ' || value[last - 1] == '\t')) --last; + return value.substr(first, last - first); +} + +std::string unquote(const std::string& value) { + if (value.size() >= 2 && ((value.front() == '"' && value.back() == '"') || + (value.front() == '\'' && value.back() == '\''))) { + return value.substr(1, value.size() - 2); + } + return value; +} + +bool truthy(const std::string& value) { + return value == "1" || value == "yes" || value == "true" || value == "on"; +} + +// The layout names the renderer accepts, in the order its reference lists them. +const char* const kLayouts[] = {"2.0", "3.1", "5.1", "7.1", "5.1.2", + "5.1.4", "7.1.2", "7.1.4", "9.1.4", "9.1.6"}; + +} // namespace + +const char* layout_list() { + return "2.0, 3.1, 5.1, 7.1, 5.1.2, 5.1.4, 7.1.2, 7.1.4, 9.1.4, 9.1.6"; +} + +bool valid_layout(const std::string& layout) { + for (const char* name : kLayouts) { + if (layout == name) return true; + } + return false; +} + +Config parse_config(const std::string& script_opts, std::string* warnings) { + Config config; + std::map options; + std::size_t start = 0; + while (start <= script_opts.size()) { + std::size_t comma = script_opts.find(',', start); + if (comma == std::string::npos) comma = script_opts.size(); + const std::string item = trim(script_opts.substr(start, comma - start)); + const std::size_t equals = item.find('='); + if (equals != std::string::npos) { + options[trim(item.substr(0, equals))] = unquote(trim(item.substr(equals + 1))); + } + if (comma == script_opts.size()) break; + start = comma + 1; + } + + auto unsupported = [warnings](const std::string& key) { + if (warnings != nullptr) { + if (!warnings->empty()) warnings->append("; "); + warnings->append("unknown option " + key); + } + }; + + for (const auto& entry : options) { + const std::string& key = entry.first; + const std::string& value = entry.second; + if (key == "joc-enabled") { + config.enabled = truthy(value); + } else if (key == "joc-output") { + if (value == "binaural" || value == "2ch" || value == "0") { + config.output = 0; + } else if (value == "speaker" || value == "1") { + config.output = 1; + } else { + unsupported(key + "=" + value); + } + } else if (key == "joc-layout") { + if (valid_layout(value)) { + config.layout = value; + } else { + unsupported(key + "=" + value); + } + } else if (key == "joc-hrtf-source") { + if (value == "sofa") { + config.hrtf_source = 0; + } else if (value == "rosella" || value == "personalized") { + config.hrtf_source = 1; + } else { + unsupported(key + "=" + value); + } + } else if (key == "joc-hrtf") { + config.hrtf_file = value; + } else if (key == "joc-mode") { + if (value == "near") config.binaural_mode = 1; + else if (value == "far") config.binaural_mode = 2; + else if (value == "mid") config.binaural_mode = 3; + else unsupported(key + "=" + value); + } else if (key == "joc-gain-db") { + config.gain_db = std::atof(value.c_str()); + } else if (key == "joc-tail") { + config.tail_seconds = std::atof(value.c_str()); + } else if (key == "joc-int24") { + config.force_int24 = truthy(value); + } else if (key == "joc-object-delay") { + config.object_delay_samples = static_cast(std::strtoul(value.c_str(), nullptr, 10)); + } else if (key == "joc-threads") { + config.native_threads = static_cast(std::strtoul(value.c_str(), nullptr, 10)); + } else if (key == "joc-ffmpeg") { + config.ffmpeg = value; + } else if (key == "joc-core") { + config.core_dll = value; + } else if (key == "joc-wasapi") { + if (value == "auto" || value == "yes" || value == "no") config.wasapi = value; + else unsupported(key + "=" + value); + } else if (key == "joc-exclusive") { + config.exclusive = truthy(value); + } else if (key == "joc-verbose") { + config.verbose = truthy(value); + } else if (key == "joc-attach") { + config.attach = truthy(value); + } else if (key == "joc-log") { + config.log_path = value; + } else if (key == "joc-mute-until-ready") { + config.mute_until_ready = truthy(value); + } else if (key == "joc-hrtf-cache") { + if (value == "auto" || value == "memory" || value == "disk" || value == "none") { + config.hrtf_cache = value; + } else { + unsupported(key + "=" + value); + } + } else if (key == "joc-hrtf-cache-dir") { + config.hrtf_cache_dir = value; + } else if (key == "joc-chunk") { + const double seconds = std::atof(value.c_str()); + config.chunk_seconds = (seconds >= 0.25 && seconds <= 10.0) ? seconds : 2.0; + } else { + unsupported(key); + } + } + return config; +} + +} // namespace joc_mpv diff --git a/src/plugin/config.h b/src/plugin/config.h new file mode 100644 index 0000000..f40771e --- /dev/null +++ b/src/plugin/config.h @@ -0,0 +1,56 @@ +#pragma once + +#include + +namespace joc_mpv { + +// Everything the plugin can be told through mpv's own configuration file: +// script-opts keys are "joc-=" (see config/mpv.conf.example). +struct Config { + bool enabled = true; + // 0 = binaural (2 channels), 1 = speaker layout (N channels). + int output = 0; + std::string layout = "7.1"; + // 0 = SOFA, 1 = Rosella personalized headphone model. + int hrtf_source = 0; + std::string hrtf_file; // empty: \\HRTF\\binaural. + // 1 = near, 2 = far, 3 = mid (the renderer's own default). + int binaural_mode = 3; + double gain_db = 0.0; + double tail_seconds = 5.0; + bool force_int24 = false; + unsigned object_delay_samples = 1473; + unsigned native_threads = 0; + std::string ffmpeg = "ffmpeg"; + std::string core_dll; // empty: \\joc_core.dll + // auto: leave mpv's audio output alone; yes: force the WASAPI AO. + std::string wasapi = "auto"; + bool exclusive = false; + bool verbose = false; + // no = serve the rendered stream without adding it to the player; used to + // capture exactly what the plugin would deliver, and for debugging. + bool attach = true; + // Silence the file's own audio track until the rendered one is selected, so + // the opening moments are not the plain bed. Only candidate inputs are + // muted, and only for as long as the probe takes. + bool mute_until_ready = true; + // SOFA compilation cache: auto (disk under the mpv config directory, memory + // if that is unavailable), memory, disk, none. + std::string hrtf_cache = "auto"; + std::string hrtf_cache_dir; + // Log file path; empty means \joc_decoder.log. + std::string log_path; + // Samples requested per HTTP response, in seconds of audio. A bounded + // response makes mpv come back with a fresh range request after a seek + // instead of reading through everything in between. + double chunk_seconds = 2.0; +}; + +// Parses mpv's script-opts value ("joc-output=binaural,joc-hrtf=..."); unknown +// keys are ignored so an mpv.conf written for a newer build still loads. +Config parse_config(const std::string& script_opts, std::string* warnings); + +const char* layout_list(); +bool valid_layout(const std::string& layout); + +} // namespace joc_mpv diff --git a/src/plugin/http_server.cpp b/src/plugin/http_server.cpp new file mode 100644 index 0000000..4822865 --- /dev/null +++ b/src/plugin/http_server.cpp @@ -0,0 +1,222 @@ +#include "http_server.h" + +#include +#include + +#include +#include +#include +#include + +namespace joc_mpv { +namespace { + +bool winsock_ready() { + static const bool ready = [] { + WSADATA data{}; + return WSAStartup(MAKEWORD(2, 2), &data) == 0; + }(); + return ready; +} + +std::string lower(std::string text) { + for (char& ch : text) { + if (ch >= 'A' && ch <= 'Z') ch = static_cast(ch - 'A' + 'a'); + } + return text; +} + +const char* status_text(int status) { + switch (status) { + case 200: return "OK"; + case 206: return "Partial Content"; + case 400: return "Bad Request"; + case 404: return "Not Found"; + case 416: return "Range Not Satisfiable"; + default: return "Internal Server Error"; + } +} + +bool send_all(SOCKET socket, const char* data, std::size_t size) { + while (size > 0) { + const int chunk = static_cast(std::min(size, 1u << 20)); + const int sent = ::send(socket, data, chunk, 0); + if (sent <= 0) return false; + data += sent; + size -= static_cast(sent); + } + return true; +} + +} // namespace + +bool ResponseWriter::write(const void* data, std::size_t size) { + if (!ok_) return false; + char header[32]; + const int header_length = std::snprintf(header, sizeof(header), "%zx\r\n", size); + if (!send_all(static_cast(socket_), header, static_cast(header_length)) || + !send_all(static_cast(socket_), static_cast(data), size) || + !send_all(static_cast(socket_), "\r\n", 2)) { + ok_ = false; + return false; + } + return true; +} + +HttpServer::~HttpServer() { stop(); } + +bool HttpServer::start(HttpHandler handler, unsigned short* port, std::string* error) { + if (running_) return true; + if (!winsock_ready()) { + if (error != nullptr) *error = "Winsock failed to initialize"; + return false; + } + handler_ = std::move(handler); + const SOCKET listener = ::socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); + if (listener == INVALID_SOCKET) { + if (error != nullptr) *error = "cannot create the audio socket"; + return false; + } + BOOL reuse = TRUE; + setsockopt(listener, SOL_SOCKET, SO_REUSEADDR, reinterpret_cast(&reuse), + sizeof(reuse)); + sockaddr_in address{}; + address.sin_family = AF_INET; + address.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + address.sin_port = 0; + if (::bind(listener, reinterpret_cast(&address), sizeof(address)) != 0 || + ::listen(listener, 8) != 0) { + closesocket(listener); + if (error != nullptr) *error = "cannot bind the loopback audio port"; + return false; + } + sockaddr_in bound{}; + int length = sizeof(bound); + if (getsockname(listener, reinterpret_cast(&bound), &length) == 0 && port != nullptr) { + *port = ntohs(bound.sin_port); + } + listener_ = static_cast(listener); + running_ = true; + thread_ = std::thread(&HttpServer::accept_loop, this); + return true; +} + +void HttpServer::stop() { + if (!running_) return; + running_ = false; + const SOCKET listener = static_cast(listener_); + listener_ = ~static_cast(0); + closesocket(listener); + if (thread_.joinable()) thread_.join(); + // Connection threads end when their socket fails or the source is closed; + // joining them keeps the handler and the source alive until then. + for (std::thread& worker : workers_) { + if (worker.joinable()) worker.join(); + } + workers_.clear(); + handler_ = nullptr; +} + +void HttpServer::accept_loop() { + const SOCKET listener = static_cast(listener_); + while (running_) { + const SOCKET client = ::accept(listener, nullptr, nullptr); + if (client == INVALID_SOCKET) { + if (!running_) break; + continue; + } + DWORD timeout = 5000; + setsockopt(client, SOL_SOCKET, SO_RCVTIMEO, reinterpret_cast(&timeout), + sizeof(timeout)); + setsockopt(client, SOL_SOCKET, SO_SNDTIMEO, reinterpret_cast(&timeout), + sizeof(timeout)); + workers_.emplace_back(&HttpServer::serve, this, static_cast(client)); + } +} + +void HttpServer::serve(std::uintptr_t client_value) { + const SOCKET client = static_cast(client_value); + std::string request; + char buffer[2048]; + while (request.find("\r\n\r\n") == std::string::npos) { + const int got = ::recv(client, buffer, sizeof(buffer), 0); + if (got <= 0) { + closesocket(client); + return; + } + request.append(buffer, static_cast(got)); + if (request.size() > 16384) { + closesocket(client); + return; + } + } + + HttpRequest parsed; + std::size_t line_end = request.find("\r\n"); + if (line_end != std::string::npos) { + const std::string line = request.substr(0, line_end); + const std::size_t first = line.find(' '); + const std::size_t second = (first == std::string::npos) ? std::string::npos + : line.find(' ', first + 1); + if (first != std::string::npos && second != std::string::npos) { + parsed.method = line.substr(0, first); + parsed.target = line.substr(first + 1, second - first - 1); + } + std::size_t position = line_end + 2; + while (position < request.size()) { + const std::size_t end = request.find("\r\n", position); + if (end == std::string::npos) break; + const std::string header_line = request.substr(position, end - position); + position = end + 2; + if (header_line.empty()) break; + const std::size_t colon = header_line.find(':'); + if (colon == std::string::npos) continue; + const std::string name = lower(header_line.substr(0, colon)); + std::string value = header_line.substr(colon + 1); + while (!value.empty() && (value.front() == ' ' || value.front() == '\t')) { + value.erase(0, 1); + } + if (name != "range" || value.compare(0, 6, "bytes=") != 0) continue; + value.erase(0, 6); + const std::size_t dash = value.find('-'); + if (dash == std::string::npos) continue; + const std::string first_text = value.substr(0, dash); + const std::string last_text = value.substr(dash + 1); + if (first_text.empty()) continue; // suffix ranges are not used by mpv + parsed.has_range = true; + parsed.range_start = std::strtoull(first_text.c_str(), nullptr, 10); + if (!last_text.empty()) { + parsed.has_range_end = true; + parsed.range_end = std::strtoull(last_text.c_str(), nullptr, 10); + } + } + } + + HttpResponse response; + if (handler_) handler_(parsed, &response); + else response.status = 404; + + std::string head; + head += "HTTP/1.1 " + std::to_string(response.status) + " " + status_text(response.status) + + "\r\n"; + head += response.headers; + if (response.stream) { + head += "Transfer-Encoding: chunked\r\n"; + } else { + head += "Content-Length: " + std::to_string(response.body.size()) + "\r\n"; + } + head += "Connection: close\r\n\r\n"; + + if (send_all(client, head.data(), head.size())) { + if (response.stream) { + ResponseWriter writer(static_cast(client)); + response.stream(writer); + send_all(client, "0\r\n\r\n", 5); + } else { + send_all(client, response.body.data(), response.body.size()); + } + } + closesocket(client); +} + +} // namespace joc_mpv diff --git a/src/plugin/http_server.h b/src/plugin/http_server.h new file mode 100644 index 0000000..fb94663 --- /dev/null +++ b/src/plugin/http_server.h @@ -0,0 +1,66 @@ +#pragma once + +#include +#include +#include +#include +#include + +namespace joc_mpv { + +struct HttpRequest { + std::string method; + std::string target; + bool has_range = false; + std::uint64_t range_start = 0; + std::uint64_t range_end = 0; // inclusive + bool has_range_end = false; +}; + +// Writer handed to a streaming response: every write() becomes one HTTP chunk. +class ResponseWriter { +public: + explicit ResponseWriter(std::uintptr_t socket) : socket_(socket) {} + bool write(const void* data, std::size_t size); + bool ok() const { return ok_; } + +private: + std::uintptr_t socket_; + bool ok_ = true; +}; + +struct HttpResponse { + int status = 200; + std::string headers; // one "Name: value\r\n" per line + std::string body; // used when stream is empty + // Set for a chunked response: the server sends the headers, then calls this + // with a writer that frames the data, then terminates the chunked body. + std::function stream; +}; + +using HttpHandler = std::function; + +// Minimal HTTP/1.1 server on 127.0.0.1 serving one resource with byte ranges. +// A seekable, continuously streaming audio source is what lets mpv's own +// demuxer, cache, A/V sync, WASAPI output and seeking keep working unmodified. +class HttpServer { +public: + HttpServer() = default; + ~HttpServer(); + HttpServer(const HttpServer&) = delete; + HttpServer& operator=(const HttpServer&) = delete; + + bool start(HttpHandler handler, unsigned short* port, std::string* error); + void stop(); + +private: + void accept_loop(); + void serve(std::uintptr_t client_socket); + HttpHandler handler_; + std::uintptr_t listener_ = ~static_cast(0); + std::thread thread_; + std::vector workers_; + bool running_ = false; +}; + +} // namespace joc_mpv diff --git a/src/plugin/wav.cpp b/src/plugin/wav.cpp new file mode 100644 index 0000000..34d7ce3 --- /dev/null +++ b/src/plugin/wav.cpp @@ -0,0 +1,116 @@ +#include "wav.h" + +#include + +namespace joc_mpv { +namespace { + +constexpr std::uint32_t kFl = 0x00000001u; +constexpr std::uint32_t kFr = 0x00000002u; +constexpr std::uint32_t kFc = 0x00000004u; +constexpr std::uint32_t kLfe = 0x00000008u; +constexpr std::uint32_t kBl = 0x00000010u; +constexpr std::uint32_t kBr = 0x00000020u; +constexpr std::uint32_t kSl = 0x00000200u; +constexpr std::uint32_t kSr = 0x00000400u; +constexpr std::uint32_t kTfl = 0x00001000u; +constexpr std::uint32_t kTfr = 0x00004000u; +constexpr std::uint32_t kTbl = 0x00008000u; +constexpr std::uint32_t kTbr = 0x00020000u; + +void put_u16(std::string* out, std::uint16_t value) { + char bytes[2]; + std::memcpy(bytes, &value, 2); + out->append(bytes, 2); +} + +void put_u32(std::string* out, std::uint32_t value) { + char bytes[4]; + std::memcpy(bytes, &value, 4); + out->append(bytes, 4); +} + +void put_u64(std::string* out, std::uint64_t value) { + char bytes[8]; + std::memcpy(bytes, &value, 8); + out->append(bytes, 8); +} + +// KSDATAFORMAT_SUBTYPE_IEEE_FLOAT / PCM, as written by every WAV writer. +void put_subformat(std::string* out, bool is_float) { + put_u32(out, is_float ? 3u : 1u); + put_u16(out, 0x0000); + put_u16(out, 0x0010); + const unsigned char tail[8] = {0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71}; + out->append(reinterpret_cast(tail), 8); +} + +void put_fmt(std::string* out, unsigned channels, unsigned bits, std::uint32_t mask) { + const std::uint32_t rate = 48000; + const std::uint32_t block_align = channels * (bits / 8u); + out->append("fmt ", 4); + put_u32(out, 40); + put_u16(out, 0xFFFE); // WAVE_FORMAT_EXTENSIBLE + put_u16(out, static_cast(channels)); + put_u32(out, rate); + put_u32(out, rate * block_align); + put_u16(out, static_cast(block_align)); + put_u16(out, static_cast(bits)); + put_u16(out, 22); // cbSize + put_u16(out, static_cast(bits)); + put_u32(out, mask); + put_subformat(out, bits == 32); +} + +} // namespace + +std::uint32_t channel_mask(const std::string& layout, unsigned channels) { + if (layout == "2.0") return kFl | kFr; + if (layout == "3.1") return kFl | kFr | kFc | kLfe; + if (layout == "5.1") return kFl | kFr | kFc | kLfe | kBl | kBr; + if (layout == "7.1") return kFl | kFr | kFc | kLfe | kBl | kBr | kSl | kSr; + if (layout == "5.1.2") return kFl | kFr | kFc | kLfe | kBl | kBr | kTfl | kTfr; + if (layout == "5.1.4") { + return kFl | kFr | kFc | kLfe | kBl | kBr | kTfl | kTfr | kTbl | kTbr; + } + if (layout == "7.1.2") { + return kFl | kFr | kFc | kLfe | kBl | kBr | kSl | kSr | kTfl | kTfr; + } + if (layout == "7.1.4") { + return kFl | kFr | kFc | kLfe | kBl | kBr | kSl | kSr | kTfl | kTfr | kTbl | kTbr; + } + // 2-channel binaural output is plain stereo. + if (channels == 2) return kFl | kFr; + return 0; +} + +std::string wav_header(unsigned channels, unsigned bits_per_sample, std::uint32_t mask, + std::uint64_t data_bytes) { + std::string out; + const bool rf64 = (data_bytes + 128u) > 0xFFFFFFFFull; + if (!rf64) { + out.append("RIFF", 4); + put_u32(&out, static_cast(data_bytes + 60u)); + out.append("WAVE", 4); + put_fmt(&out, channels, bits_per_sample, mask); + out.append("data", 4); + put_u32(&out, static_cast(data_bytes)); + return out; + } + // RF64: the 64-bit sizes live in ds64 and the 32-bit fields are all ones. + out.append("RF64", 4); + put_u32(&out, 0xFFFFFFFFu); + out.append("WAVE", 4); + out.append("ds64", 4); + put_u32(&out, 28); + put_u64(&out, data_bytes + 96u); // file size - 8 + put_u64(&out, data_bytes); + put_u64(&out, channels == 0 ? 0 : data_bytes / (channels * (bits_per_sample / 8u))); + put_u32(&out, 0); // no table entries + put_fmt(&out, channels, bits_per_sample, mask); + out.append("data", 4); + put_u32(&out, 0xFFFFFFFFu); + return out; +} + +} // namespace joc_mpv diff --git a/src/plugin/wav.h b/src/plugin/wav.h new file mode 100644 index 0000000..8b90e5a --- /dev/null +++ b/src/plugin/wav.h @@ -0,0 +1,19 @@ +#pragma once + +#include +#include + +namespace joc_mpv { + +// Channel mask for a layout the renderer can produce. The renderer emits its +// channels in the standard WAVE order for that layout, so a WAVE_FORMAT_EXTENSIBLE +// mask tells mpv exactly which speaker each channel belongs to. Layouts wider +// than 7.1 return 0 (no mask): they cannot reach a WASAPI endpoint anyway. +std::uint32_t channel_mask(const std::string& layout, unsigned channels); + +// 68-byte WAVE_FORMAT_EXTENSIBLE header, or a 104-byte RF64 header when the data +// chunk would not fit a 32-bit size. +std::string wav_header(unsigned channels, unsigned bits_per_sample, std::uint32_t mask, + std::uint64_t data_bytes); + +} // namespace joc_mpv diff --git a/src/win_path.h b/src/win_path.h new file mode 100644 index 0000000..306ddaf --- /dev/null +++ b/src/win_path.h @@ -0,0 +1,90 @@ +// Paths handed to the Win32 file APIs. +// +// Windows refuses a path of MAX_PATH characters or more to any call that does not +// carry the \\?\ prefix. The prefix is a property of the path, not of the process: +// a component cannot inherit it from the host's manifest, so whoever calls the API +// has to add it. A file that plays from the desktop therefore stops being found +// once its folder tree is deep enough, which is what this header exists to prevent. +// +// Everything in this component that hands a path to Win32 -- or puts one on an +// ffmpeg command line, which is the same call made by the child process -- goes +// through to_wide_extended(). What is deliberately not routed through it is the +// path the component keeps for itself: the one it logs, and the one it uses as the +// container-probe cache key. Those stay in their plain form, so a log line reads +// like a path a user can paste into Explorer. +#pragma once + +#include + +#include + +namespace joc_path { + +// UTF-8 -> UTF-16, for the W APIs. Every path crosses into the OS through here: +// the narrow CRT would convert it through the ANSI code page, which is what breaks +// names like "Les Fêtes d'Hébé". +inline std::wstring to_wide(const std::string& utf8) { + if (utf8.empty()) return {}; + const int needed = MultiByteToWideChar(CP_UTF8, 0, utf8.c_str(), + static_cast(utf8.size()), nullptr, 0); + if (needed <= 0) return {}; + std::wstring out(static_cast(needed), L'\0'); + MultiByteToWideChar(CP_UTF8, 0, utf8.c_str(), static_cast(utf8.size()), out.data(), + needed); + return out; +} + +// The same path in the form the Win32 file APIs need. Three kinds of path are left +// exactly as they came in, and each of them would be broken by a prefix: +// +// * one that already carries \\?\, which makes this idempotent; +// * one that is not fully qualified -- a relative path, or the ffmpeg setting +// when it is a bare executable name that PATH resolves. \\?\ is undefined for +// those; +// * one with a "." or ".." segment, because \\?\ switches off the normalization +// that would resolve it. +// +// The separators are settled first for the same reason: once the prefix is on, +// nothing turns a forward slash into a backslash any more, and both of the checks +// above have to see the path the way the file system will. +inline std::wstring to_wide_extended(const std::wstring& path) { + if (path.empty()) return path; + if (path.compare(0, 4, L"\\\\?\\") == 0) return path; + + std::wstring plain = path; + for (wchar_t& character : plain) { + if (character == L'/') character = L'\\'; + } + + const bool unc = plain.size() >= 2 && plain[0] == L'\\' && plain[1] == L'\\'; + const bool drive = plain.size() >= 3 && plain[1] == L':' && plain[2] == L'\\'; + if (!unc && !drive) return path; + if (plain.find(L"\\.\\") != std::wstring::npos || + plain.find(L"\\..\\") != std::wstring::npos) { + return path; + } + + // A UNC path drops its two leading separators; everything else is copied whole. + std::wstring out = unc ? L"\\\\?\\UNC\\" : L"\\\\?\\"; + out.append(plain, unc ? 2 : 0, std::wstring::npos); + return out; +} + +inline std::wstring to_wide_extended(const std::string& utf8) { + return to_wide_extended(to_wide(utf8)); +} + +// UTF-16 -> UTF-8, the direction the component reports paths in. +inline std::string to_utf8(const std::wstring& wide) { + if (wide.empty()) return {}; + const int needed = WideCharToMultiByte(CP_UTF8, 0, wide.c_str(), + static_cast(wide.size()), nullptr, 0, nullptr, + nullptr); + if (needed <= 0) return {}; + std::string out(static_cast(needed), '\0'); + WideCharToMultiByte(CP_UTF8, 0, wide.c_str(), static_cast(wide.size()), out.data(), + needed, nullptr, nullptr); + return out; +} + +} // namespace joc_path diff --git a/third_party/joc/include/joc_core.h b/third_party/joc/include/joc_core.h new file mode 100644 index 0000000..40d6a96 --- /dev/null +++ b/third_party/joc/include/joc_core.h @@ -0,0 +1,492 @@ +/* + * joc_core.h -- JustOneCacophony C++ Core, public ABI. Pure C. + * + * This header is the single authoritative definition of the Core's public + * parameter/error surface. Frontends (thin Python CLI, joc_dump, foobar2000, + * MPV, FFmpeg) only ever fill these POD structs and read these POD results; + * no audio data, no internal DSP concept, and no Python type crosses this + * boundary. + * + * Stability tiers + * --------------- + * [T1] host tier + * joc_abi_version / joc_version_string / joc_build_info, joc_error, + * joc_error_name / joc_error_stage, joc_last_error_detail. + * Stable, versioned, safe for media hosts. + * + * [T2] bitstream / verification tier + * joc_parse_eac3_frame, joc_parse_id14, joc_frame_params, joc_emdf_info. + * These deliberately expose the dequantized JOC matrix coefficients so the + * bitstream front-end can be validated bit-exactly and driven by tooling + * (joc_dump) and A/B harnesses. Media hosts must NOT use this tier; they + * use the task/stream API (added in later milestones). + * + * Conventions + * ----------- + * * every struct's first two fields are struct_size / struct_version; + * * all arrays are fixed size and POD, no pointers, no allocation; + * * every function returns joc_error (JOC_OK == 0); + * * joc_last_error_detail() returns a thread-local message that stays valid + * until the next Core call on the same thread. + */ +#pragma once + +#include +#include + +#include "joc_version.h" + +#define JOC_ABI_VERSION 5u +#define JOC_FRAME_PARAMS_VERSION 1u +#define JOC_EMDF_INFO_VERSION 1u +#define JOC_TASK_CONFIG_VERSION 3u +#define JOC_TASK_RESULT_VERSION 2u +#define JOC_EVENT_VERSION 1u + +/* JOC_STATIC: this branch exists for building the sources directly into an application, where nothing is imported or exported. */ +#if defined(JOC_STATIC) + #define JOC_API + #define JOC_CALL __cdecl +#elif defined(_WIN32) + #if defined(JOC_BUILD_DLL) + #define JOC_API __declspec(dllexport) + #else + #define JOC_API __declspec(dllimport) + #endif + #define JOC_CALL __cdecl +#else + #define JOC_API __attribute__((visibility("default"))) + #define JOC_CALL +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/* ------------------------------------------------------------------ */ +/* Fixed layout constants (single source of truth for every frontend) */ +/* ------------------------------------------------------------------ */ +enum { + JOC_FRAME_SAMPLES = 1536, /* E-AC-3 frame = 24 * 64 */ + JOC_TIMESLOTS = 24, + JOC_SUBBANDS = 64, + JOC_CORE_CHANNELS = 5, /* L R C Ls Rs (JOC order) */ + JOC_MAX_CORE_CHANNELS = 7, /* dmx_config_idx 1/2/4 declare 7 */ + JOC_OUTPUT_CHANNELS = 16, /* ch0 = LFE, ch1..15 = objects */ + JOC_MAX_OBJECTS = 15, + JOC_MAX_DPOINTS = 2, + JOC_MAX_PARAMETER_BANDS = 23, + JOC_MAX_EMDF_PAYLOADS = 16, + JOC_SPEAKER_BLOCK_SAMPLES = 32, + JOC_BINAURAL_BLOCK_SAMPLES = 512, + JOC_BINAURAL_QMF_BANDS = 64, + JOC_BINAURAL_HYBRID_BANDS = 77, + JOC_QMF_HOP_SAMPLES = 64, + JOC_BINAURAL_LATENCY_SAMPLES = 961, + JOC_LFE_DELAY_SAMPLES = 1217 +}; + +/* ------------------------------------------------------------------ */ +/* [T1] library / error surface */ +/* ------------------------------------------------------------------ */ +typedef enum joc_error { + JOC_OK = 0, + JOC_ERR_INVALID_ARGUMENT, + JOC_ERR_INVALID_CONFIG, + JOC_ERR_OUT_OF_MEMORY, + JOC_ERR_IO, + JOC_ERR_UNSUPPORTED_PLATFORM, + JOC_ERR_LIBRARY_MISSING, + /* input / bitstream */ + JOC_ERR_INPUT_NOT_FOUND, + JOC_ERR_INPUT_FORMAT, + JOC_ERR_EAC3_SYNCFRAME, + JOC_ERR_EMDF_TRANSPORT, + JOC_ERR_EMDF_SYNTAX, + JOC_ERR_JOC_SYNTAX, + JOC_ERR_JOC_UNSUPPORTED_VARIANT, + JOC_ERR_OAMD_SYNTAX, + JOC_ERR_OAMD_UNSUPPORTED_VARIANT, + JOC_ERR_BITSTREAM_TRUNCATED, + JOC_ERR_BITSTREAM_PADDING, + /* resources */ + JOC_ERR_HRTF_NOT_FOUND, + JOC_ERR_HRTF_FORMAT, + JOC_ERR_HRTF_VERSION, + JOC_ERR_HRTF_HASH, + JOC_ERR_HRTF_UNSUPPORTED_CONVENTION, + /* rendering / output */ + JOC_ERR_LAYOUT_UNSUPPORTED, + JOC_ERR_RENDER_FAILED, + JOC_ERR_OUTPUT_OPEN, + JOC_ERR_OUTPUT_WRITE, + JOC_ERR_OUTPUT_CLIP_ABORT, + JOC_ERR_ADM_VALIDATION, + /* task / stream */ + JOC_ERR_CANCELLED, + JOC_ERR_STATE, + JOC_ERR_NOT_SUPPORTED, + JOC_ERR_INTERNAL +} joc_error; + +JOC_API uint32_t JOC_CALL joc_abi_version(void); +JOC_API const char* JOC_CALL joc_version_string(void); +JOC_API const char* JOC_CALL joc_build_info(void); +/* Struct sizes, so a binding can assert its layout matches the library instead of + * assuming (mismatches are otherwise silent memory corruption). */ +JOC_API uint32_t JOC_CALL joc_event_size(void); +JOC_API uint32_t JOC_CALL joc_task_config_size(void); +JOC_API uint32_t JOC_CALL joc_task_result_size(void); +JOC_API const char* JOC_CALL joc_error_name(joc_error code); +JOC_API const char* JOC_CALL joc_error_stage(joc_error code); +/* Thread-local structured detail for the most recent failing call. */ +JOC_API const char* JOC_CALL joc_last_error_detail(void); + +/* ------------------------------------------------------------------ */ +/* [T2] bitstream / verification tier */ +/* ------------------------------------------------------------------ */ + +/* One EMDF payload directory entry. bit_offset is the MSB-first bit + * position of the payload's first byte inside the syncframe, exactly as the + * EMDF container syntax defines it (payloads are not byte aligned in general). */ +typedef struct joc_emdf_payload_info { + uint8_t id; + uint8_t reserved[3]; + uint16_t sample_offset; /* EMDF outer smpoffst, 11 bits */ + uint16_t reserved2; + uint32_t bit_offset; + uint32_t size; /* payload bytes */ +} joc_emdf_payload_info; + +typedef struct joc_emdf_info { + uint32_t struct_size; + uint32_t struct_version; + uint32_t start_bit; /* container syncword bit position */ + uint32_t container_bytes; /* 4 + declared length */ + uint32_t payload_count; + uint32_t reserved; + joc_emdf_payload_info payloads[JOC_MAX_EMDF_PAYLOADS]; +} joc_emdf_info; + +/* Per-object ID14/JOC descriptor plus its dequantized matrix. + * dq[dp][ch][pb] is zero filled outside [0,n_dpoints) x [0,n_channels) x + * [0,n_bands). Absent objects are entirely zero. */ +typedef struct joc_object_params { + uint8_t present; + uint8_t num_bands_idx; + uint8_t n_bands; + uint8_t sparse; /* 0 = dense (MTX), 1 = sparse (IDX+VEC) */ + uint8_t quant_idx; /* 0 = 96 levels, 1 = 192 levels */ + uint8_t slope_idx; /* 0 = interpolate, 1 = step at offset_ts */ + uint8_t num_dpoints_bits; + uint8_t n_dpoints; + uint8_t offset_ts[JOC_MAX_DPOINTS]; + uint8_t reserved[2]; + double dq[JOC_MAX_DPOINTS][JOC_MAX_CORE_CHANNELS][JOC_MAX_PARAMETER_BANDS]; +} joc_object_params; + +typedef struct joc_frame_params { + uint32_t struct_size; + uint32_t struct_version; + uint8_t dmx_config_idx; + uint8_t num_objects_bits; + uint8_t ext_config_idx; + uint8_t n_objects; + uint8_t n_channels; /* 5 or 7 */ + uint8_t clipgain_x_bits; + uint8_t clipgain_y_bits; + uint8_t objects_clamped; /* num_objects_bits+1 exceeded 15 */ + uint32_t seq_count; /* 10-bit JOC sequence counter, parsed only */ + uint32_t present_mask; /* bit i == object i present */ + uint32_t data_end_bits; /* bit position just after joc_data */ + uint32_t trailing_bits; /* bits left after joc_data (padding/ext) */ + uint8_t tail_bytes[8]; /* first up to 8 trailing bytes, for A/B */ + double clipgain; /* 1 + (y/32) * 2^(x-4), bit-exact */ + joc_object_params objects[JOC_MAX_OBJECTS]; +} joc_frame_params; + +/* Parse an EMDF ID14 (JOC) payload. */ +JOC_API joc_error JOC_CALL joc_parse_id14(const uint8_t* payload, size_t payload_size, + joc_frame_params* out_params); + +/* Locate the contiguous JOC EMDF container inside one E-AC-3 syncframe and + * parse its ID14 payload. out_emdf may be NULL. */ +JOC_API joc_error JOC_CALL joc_parse_eac3_frame(const uint8_t* frame, size_t frame_size, + joc_frame_params* out_params, + joc_emdf_info* out_emdf); + +/* Copy one payload's bytes out of a syncframe (MSB-first bit extraction, which + * equals a memcpy for byte-aligned containers). out_size receives the payload + * byte count; pass out == NULL to query only the size. */ +JOC_API joc_error JOC_CALL joc_extract_payload(const uint8_t* frame, size_t frame_size, + const joc_emdf_payload_info* payload, + uint8_t* out, size_t out_capacity, + size_t* out_size); + +/* E-AC-3 syncframe traversal: given the offset of a frame start, report its + * byte length so a host can walk a bare E-AC-3 stream without duplicating + * frmsiz logic. Rejects resynchronisation (no silent recovery). */ +JOC_API joc_error JOC_CALL joc_eac3_frame_bytes(const uint8_t* data, size_t size, + size_t offset, size_t* out_frame_bytes); + +/* Strict trailing-bit check for the JOC payload (A/B robustness corpus). + * Returns JOC_ERR_BITSTREAM_PADDING when more than 7 bits are left over or the + * leftover bits are not zero. */ +JOC_API joc_error JOC_CALL joc_check_id14_padding(const uint8_t* payload, size_t payload_size, + uint32_t* out_trailing_bits); + +/* ================================================================== */ +/* [T1] host tier: task, telemetry and control */ +/* ================================================================== */ + +/* ---- 1. events ---------------------------------------------------- */ +/* + * Events carry state only: frame/sample counters, stage, progress, statistics, + * warnings, errors and paths. Audio never travels through an event; a fixed + * size POD with no pointers keeps that enforceable (see the static assertion in + * the implementation). + */ +typedef enum joc_event_type { + JOC_EV_TASK_STARTED = 0x0001, + JOC_EV_TASK_STATE_CHANGED = 0x0002, + JOC_EV_TASK_COMPLETED = 0x0003, + JOC_EV_TASK_FAILED = 0x0004, + JOC_EV_TASK_CANCELLED = 0x0005, + JOC_EV_INPUT_OPENED = 0x0101, + JOC_EV_METADATA_INDEXED = 0x0103, + JOC_EV_HRTF_LOADED = 0x0110, + JOC_EV_RENDERER_INITIALIZED = 0x0120, + JOC_EV_PROGRESS = 0x0201, + JOC_EV_STAGE_CHANGED = 0x0202, + JOC_EV_JOC_FRAME_STATS = 0x0301, + JOC_EV_OAMD_STATS = 0x0302, + JOC_EV_OUTPUT_STATS = 0x0303, + JOC_EV_OUTPUT_OPENED = 0x0401, + JOC_EV_OUTPUT_FORMAT_DECIDED = 0x0402, + JOC_EV_OUTPUT_FINALIZED = 0x0403, + JOC_EV_LOG = 0x0501, + JOC_EV_WARNING = 0x0502, + JOC_EV_ERROR = 0x0503 +} joc_event_type; + +typedef enum joc_stage { + JOC_STAGE_IDLE = 0, + JOC_STAGE_INPUT = 1, + JOC_STAGE_METADATA = 2, + JOC_STAGE_DECODE = 3, + JOC_STAGE_JOC = 4, + JOC_STAGE_RENDER = 5, + JOC_STAGE_OUTPUT = 6, + JOC_STAGE_DONE = 7 +} joc_stage; + +enum { JOC_LOG_TRACE = 0, JOC_LOG_DEBUG = 1, JOC_LOG_INFO = 2, JOC_LOG_NOTICE = 3, + JOC_LOG_WARNING = 4, JOC_LOG_ERROR = 5, JOC_LOG_FATAL = 6 }; + +typedef struct joc_event { + uint32_t struct_size; + uint32_t type; + uint64_t sequence; + uint64_t timestamp_us; + uint64_t current_frame; + uint64_t total_frames; + uint64_t current_sample; + uint64_t total_samples; + uint32_t stage; + uint32_t backend; + double progress; /* 0..1, -1 = unknown */ + double elapsed_seconds; + double realtime_factor; + uint64_t output_samples; + uint64_t output_bytes; + double output_duration_seconds; + joc_error error_code; + uint32_t log_level; + char stage_name[32]; + char message[256]; +} joc_event; + +typedef void (JOC_CALL *joc_event_fn)(void* user, const joc_event* event); + +typedef struct joc_event_sink { + uint32_t struct_size; + joc_event_fn callback; + void* user; + uint32_t min_type; /* 0 = no filter */ + uint32_t max_type; /* 0 = no filter */ +} joc_event_sink; + +/* ---- 2. cancellation ---------------------------------------------- */ +typedef struct joc_cancel_token joc_cancel_token; + +JOC_API joc_cancel_token* JOC_CALL joc_cancel_token_create(void); +JOC_API void JOC_CALL joc_cancel_token_request(joc_cancel_token* token); +JOC_API int32_t JOC_CALL joc_cancel_token_is_requested(const joc_cancel_token* token); +JOC_API void JOC_CALL joc_cancel_token_destroy(joc_cancel_token* token); + +/* ---- 3. task configuration and results ---------------------------- */ +typedef enum joc_operation { + JOC_OP_ADM_BWF = 0, + JOC_OP_SPEAKER = 1, + JOC_OP_BINAURAL = 2 +} joc_operation; + +typedef enum joc_output_format { + JOC_FORMAT_FLOAT32 = 0, + JOC_FORMAT_PCM24 = 1 +} joc_output_format; + +typedef enum joc_binaural_mode { + JOC_BINAURAL_OFF = 0, + JOC_BINAURAL_NEAR = 1, + JOC_BINAURAL_FAR = 2, + JOC_BINAURAL_MID = 3 +} joc_binaural_mode; + +typedef enum joc_trajectory_mode { + JOC_TRAJECTORY_COMPACT = 0, + JOC_TRAJECTORY_DENSE64 = 1 +} joc_trajectory_mode; + +/* What to do when an int24 WAV would clip (peak outside [-1, 1]). Mirrors the + * reference CLI's --clip-action; ADM BWF output is always int24 and does not + * consult this because no alternative format exists there. */ +typedef enum joc_clip_action { + JOC_CLIP_ASK = 0, /* prompt on stdin; an error when stdin is not a terminal */ + JOC_CLIP_CONTINUE = 1, /* write int24, truncating out-of-range values */ + JOC_CLIP_FLOAT32 = 2, /* switch the output to float32 */ + JOC_CLIP_ABORT = 3 /* fail the task */ +} joc_clip_action; + +/* Compiled-HRTF cache policy for a SOFA input; the .jochrtf itself is an + * internal artifact of the compile step. */ +typedef enum joc_hrtf_cache_policy { + JOC_HRTF_CACHE_NONE = 0, /* compile and discard */ + JOC_HRTF_CACHE_MEMORY = 1, /* compile and keep in this process (default) */ + JOC_HRTF_CACHE_DISK = 2 /* compile, reuse and write /.jochrtf */ +} joc_hrtf_cache_policy; + +enum { JOC_TASK_F_SKIP_SHA256 = 1u, JOC_TASK_F_KEEP_INTERMEDIATE = 2u, + JOC_TASK_F_QUIET = 4u, JOC_TASK_F_METADATA_ONLY = 8u }; + +typedef struct joc_task_config { + uint32_t struct_size; + uint32_t struct_version; + + /* input */ + const char* input_path; /* .eac3/.ec3/.m4a/... */ + const char* ffmpeg_path; /* NULL = FFMPEG, then "ffmpeg" on PATH */ + const char* bed_path; /* NULL = decode the core PCM with ffmpeg */ + const char* work_dir; /* NULL = a temporary directory */ + double eac3_drc_scale; /* 0 = DRC off (reference default) */ + int32_t eac3_target_level; /* -31..0, 0 = not applied */ + + /* output */ + uint32_t operation; + const char* output_path; + uint32_t output_format; /* requested format for speaker/binaural */ + uint32_t flags; + uint32_t clip_action; /* joc_clip_action; JOC_CLIP_ASK by default */ + + /* rendering */ + const char* speaker_layout_name; + uint32_t speaker_metadata_offset; /* default 1473 */ + uint32_t binaural_mode; + const char* hrtf_path; /* .jochrtf */ + const char* kernels_path; /* rosella_kernels.npz */ + double binaural_tail_seconds; /* default 5.0 */ + double binaural_tail_threshold; /* binaural only; 0 disables trimming */ + uint32_t binaural_chunk_frames; /* accepted for CLI parity; no effect */ + + /* ADM */ + uint32_t adm_binaural_mode; /* DBMD segment 10 encoding */ + uint32_t trajectory_mode; + + /* generic */ + uint32_t object_delay_samples; /* default 1473 */ + double gain_db; /* default 0 */ + uint64_t duration_frames; /* 0 = the whole stream */ + uint32_t progress_interval_frames; /* default 1000 */ + uint32_t native_threads; /* 0 = automatic */ + + /* diagnostics */ + uint32_t print_metadata; /* 0 none, 1 summary, 2 per frame */ + const char* metadata_json_path; /* NULL = no JSON summary */ + + joc_cancel_token* cancel; /* optional */ + + /* Binaural HRTF input (config version 2): when hrtf_sofa_path is set the + * library compiles it with hrtf_cache_policy / hrtf_cache_dir / hrtf_radius_m + * and hrtf_path is unused. hrtf_path stays the advanced override that reads + * a .jochrtf directly. */ + const char* hrtf_sofa_path; /* SOFA SimpleFreeFieldHRIR input */ + const char* personalized_headphone_path; /* Rosella .personalized_headphone input */ + const char* hrtf_cache_dir; /* disk policy directory */ + uint32_t hrtf_cache_policy; /* joc_hrtf_cache_policy */ + uint32_t reserved0; + double hrtf_radius_m; /* SOFA measurement-radius shell */ +} joc_task_config; + +typedef enum joc_task_status { + JOC_TASK_OK = 0, + JOC_TASK_FAILED = 1, + JOC_TASK_CANCELLED = 2 +} joc_task_status; + +typedef struct joc_task_result { + uint32_t struct_size; + uint32_t struct_version; + uint32_t status; + uint32_t error_code; + char error_message[512]; + char error_stage[32]; + uint64_t input_frames; + uint64_t output_samples; + double duration_sec; + uint32_t output_format_actual; + double output_peak; + uint64_t output_over_unity_values; + uint64_t output_file_bytes; + char output_sha256[65]; /* empty when skipped */ + uint64_t oamd_payloads; + uint64_t oamd_transitions; + double t_decode_bed; + double t_render; + double t_write; + double t_total; + double t_render_dsp; /* speaker/binaural DSP calls only; 0 for ADM */ + double t_write_file; /* disk writes including the finalize; >= t_write */ +} joc_task_result; + +typedef struct joc_validation_issue { + joc_error code; + uint32_t severity; /* 0 = info, 1 = warning, 2 = error */ + char field[48]; + char message[256]; +} joc_validation_issue; + +/* ---- 4. entry points ---------------------------------------------- */ +/* Fills `issues` (up to `capacity`) and reports how many were produced. + * Returns JOC_OK when no *error*-severity issue was found. */ +JOC_API joc_error JOC_CALL joc_task_validate(const joc_task_config* config, + joc_validation_issue* issues, uint32_t capacity, + uint32_t* count); + +/* Runs the whole task on the calling thread. `sink` may be NULL; `out` may be + * NULL. On cancellation the partial output is removed and JOC_ERR_CANCELLED is + * returned with out->status = JOC_TASK_CANCELLED. */ +JOC_API joc_error JOC_CALL joc_task_execute(const joc_task_config* config, + const joc_event_sink* sink, joc_task_result* out); + +/* Serialises the stable subset of the result as JSON (no environment fields - + * those belong to the frontend). `needed` receives the required size including + * the terminator; a NULL buffer queries only the size. */ +JOC_API joc_error JOC_CALL joc_task_result_to_json(const joc_task_result* result, char* buffer, + size_t capacity, size_t* needed); + +/* The streaming (push/pull) tier lives in "joc_stream.h" so an embedder can + * include the narrow surface without the bitstream/verification tier. */ + +#ifdef __cplusplus +} /* extern "C" */ +#endif diff --git a/third_party/joc/include/joc_stream.h b/third_party/joc/include/joc_stream.h new file mode 100644 index 0000000..5c2076b --- /dev/null +++ b/third_party/joc/include/joc_stream.h @@ -0,0 +1,146 @@ +/* + * joc_stream.h -- streaming (push/pull) interface of the JustOneCacophony core. + * + * This is the narrow, embedder-facing surface: a player or decoder component + * includes only this header. It is the same shared library as joc_core.h, split + * so an integrator never has to see the bitstream/verification tier. + * + * A stream is a stateful instance for hosts that cannot wait for a whole file: + * the caller feeds E-AC-3 bytes and the core PCM of the same frames (or already + * rebuilt objects16) and pulls rendered PCM as soon as it is available. It + * mirrors the two library shapes a decoder library normally offers: this + * push/pull form for host-owned I/O, and joc_task_execute() in joc_core.h for + * library-owned file I/O. + * + * Contract: + * - all state is instance-private, so several streams coexist; + * - a stream is NOT thread safe: push and pull must come from one thread; + * - rendering is stateful (matrix interpolation, gain ramps, room tail), so a + * new position on the timeline requires decoding to continue from the start + * of the stream; there is no seek in this version; + * - the kernel latency is 961 samples for speaker/binaural output: the first + * pull after two 512-sample blocks, and flush() drains the binaural tail. + */ +#pragma once + +#include "joc_core.h" + +/* JOC_STATIC (building the sources directly into an application): joc_core.h above already installs the empty JOC_API. */ +#if defined(JOC_STATIC) && !defined(JOC_API) + #define JOC_API + #define JOC_CALL __cdecl +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct joc_stream joc_stream; + +typedef enum joc_stream_input { + JOC_STREAM_IN_EAC3 = 0, /* bare E-AC-3 syncframes (the metadata stream) */ + JOC_STREAM_IN_PCM_OBJECTS16 = 1, /* objects16 frames, planar [16][1536] each */ + JOC_STREAM_IN_CORE_PCM = 3 /* the 5.1 core PCM of the pushed E-AC-3 frames */ +} joc_stream_input; + +typedef enum joc_stream_output { + JOC_STREAM_OUT_PCM_OBJECTS16 = 0, /* objects16 frames, planar [16][1536] each */ + JOC_STREAM_OUT_SPEAKER = 1, /* interleaved [samples][channels] f32 */ + JOC_STREAM_OUT_BINAURAL = 2 /* interleaved [samples][2] f32 */ +} joc_stream_output; + +typedef struct joc_stream_config { + uint32_t struct_size; + uint32_t struct_version; + uint32_t input; + uint32_t output; + const char* speaker_layout_name; + uint32_t speaker_metadata_offset; /* default 1473 */ + uint32_t binaural_mode; /* near|mid|far; 0 means mid */ + const char* hrtf_path; /* binaural only */ + const char* kernels_path; /* binaural only */ + double binaural_tail_seconds; /* default 5.0 */ + uint32_t object_delay_samples; /* default 1473 */ + double gain_db; /* default 0 */ + uint32_t native_threads; + uint32_t reserved; + /* Binaural HRTF input, the same three shapes joc_task_config accepts: when + * hrtf_sofa_path is set the library compiles it with hrtf_cache_policy / + * hrtf_cache_dir / hrtf_radius_m and hrtf_path is unused; when + * personalized_headphone_path is set the Rosella runtime renders instead. + * hrtf_path stays the fallback/advanced input that reads a .jochrtf directly. */ + const char* hrtf_sofa_path; /* SOFA SimpleFreeFieldHRIR input */ + const char* personalized_headphone_path; /* Rosella .personalized_headphone input */ + const char* hrtf_cache_dir; /* disk cache directory for SOFA compilation */ + uint32_t hrtf_cache_policy; /* joc_hrtf_cache_policy: 0 none, 1 memory, 2 disk */ + double hrtf_radius_m; /* SOFA measurement-radius shell, default 1.0 */ +} joc_stream_config; + +typedef struct joc_stream_buffer { + uint32_t struct_size; + uint32_t struct_version; + uint32_t kind; /* which joc_stream_input/output this buffer carries */ + uint32_t channels; + uint32_t sample_rate; + uint32_t sample_count; /* in: capacity / out: produced (per channel) */ + uint32_t byte_count; /* in: capacity / out: consumed or produced bytes */ + uint32_t reserved; + const uint8_t* bytes; /* EAC3 input */ + const float* pcm; /* PCM input */ + uint8_t* out_bytes; /* reserved for encoded outputs */ + float* out_pcm; /* PCM output */ +} joc_stream_buffer; + +typedef struct joc_stream_status_info { + uint32_t struct_size; + uint32_t struct_version; + uint64_t frames_in; + uint64_t frames_out; + uint64_t samples_in; + uint64_t samples_out; + uint64_t bytes_in; + uint64_t buffered_samples; /* rendered but not yet pulled, per channel */ + uint64_t oamd_payloads; + uint64_t oamd_transitions; + /* Metadata the renderer had to work around, per audio frame: no JOC payload at + * all, a declared object count clamped to 15, and a syncframe carrying a second + * EMDF container that is not this frame's JOC metadata. */ + uint64_t missing_joc_frames; + uint64_t objects_clamped_frames; + uint64_t extra_container_frames; + /* Extra-pair identity disagreements across layers (spec 11.2 checks 1 and 2). + * The identity is metadata only, so those frames still render. */ + uint64_t chanmap_pair_mismatch_frames; + uint64_t bed_mask_mismatch_frames; + uint32_t output_channels; + uint32_t ended; /* 1 after flush() */ +} joc_stream_status_info; + +JOC_API joc_error JOC_CALL joc_stream_create(const joc_stream_config* config, joc_stream** out); + +/* Feeds one buffer. Kind selects the path: EAC3 bytes, the core PCM of those + * frames, or objects16. Consumed counts are reported so a caller can resume + * from a partial push. */ +JOC_API joc_error JOC_CALL joc_stream_push(joc_stream* stream, const joc_stream_buffer* input, + uint32_t* consumed_samples, uint32_t* consumed_bytes); + +/* Copies as many rendered samples as fit into `output` (interleaved, or planar + * for PCM_OBJECTS16) and reports how many were produced; 0 means "push more". */ +JOC_API joc_error JOC_CALL joc_stream_pull(joc_stream* stream, joc_stream_buffer* output, + uint32_t* produced_samples); + +/* Marks the end of input and drains whatever the renderer still holds (the + * binaural room tail); pull the remaining samples afterwards. */ +JOC_API joc_error JOC_CALL joc_stream_flush(joc_stream* stream); + +/* Returns the instance to its initial state (kernel, ramps, timeline, room, + * parser, counters) so the same stream can be reused for another pass. */ +JOC_API joc_error JOC_CALL joc_stream_reset(joc_stream* stream); + +JOC_API joc_error JOC_CALL joc_stream_status(const joc_stream* stream, + joc_stream_status_info* out); +JOC_API joc_error JOC_CALL joc_stream_destroy(joc_stream* stream); + +#ifdef __cplusplus +} /* extern "C" */ +#endif diff --git a/third_party/joc/include/joc_version.h b/third_party/joc/include/joc_version.h new file mode 100644 index 0000000..809f69b --- /dev/null +++ b/third_party/joc/include/joc_version.h @@ -0,0 +1,16 @@ +/* Product version of joc_core and joc_cli. + * + * This file is the single source of truth: CMakeLists.txt reads these numbers for + * project(VERSION ...), joc_version_string() returns JOC_VERSION_STRING, and the + * release workflow refuses a tag that does not match it. Bump the three numbers + * and the string together, then tag the commit with v. + */ +#ifndef JOC_VERSION_H +#define JOC_VERSION_H + +#define JOC_VERSION_MAJOR 1 +#define JOC_VERSION_MINOR 0 +#define JOC_VERSION_PATCH 0 +#define JOC_VERSION_STRING "1.0.0" + +#endif /* JOC_VERSION_H */ diff --git a/third_party/mpv/client.h b/third_party/mpv/client.h new file mode 100644 index 0000000..f970b9a --- /dev/null +++ b/third_party/mpv/client.h @@ -0,0 +1,2033 @@ +/* Copyright (C) 2017 the mpv developers + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +/* + * Note: the client API is licensed under ISC (see above) to enable + * other wrappers outside of mpv. But keep in mind that the + * mpv core is by default still GPLv2+ - unless built with + * -Dgpl=false, which makes it LGPLv2+. + */ + +#ifndef MPV_CLIENT_API_H_ +#define MPV_CLIENT_API_H_ + +#include +#include + +#ifdef _WIN32 +#define MPV_EXPORT __declspec(dllexport) +#define MPV_SELECTANY __declspec(selectany) +#elif defined(__GNUC__) || defined(__clang__) +#define MPV_EXPORT __attribute__((visibility("default"))) +#define MPV_SELECTANY +#else +#define MPV_EXPORT +#define MPV_SELECTANY +#endif + +#ifdef __cpp_decltype +#define MPV_DECLTYPE decltype +#else +#define MPV_DECLTYPE __typeof__ +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Mechanisms provided by this API + * ------------------------------- + * + * This API provides general control over mpv playback. It does not give you + * direct access to individual components of the player, only the whole thing. + * It's somewhat equivalent to MPlayer's slave mode. You can send commands, + * retrieve or set playback status or settings with properties, and receive + * events. + * + * The API can be used in two ways: + * 1) Internally in mpv, to provide additional features to the command line + * player. Lua scripting uses this. (Currently there is no plugin API to + * get a client API handle in external user code. It has to be a fixed + * part of the player at compilation time.) + * 2) Using mpv as a library with mpv_create(). This basically allows embedding + * mpv in other applications. + * + * Documentation + * ------------- + * + * The libmpv C API is documented directly in this header. Note that most + * actual interaction with this player is done through + * options/commands/properties, which can be accessed through this API. + * Essentially everything is done with them, including loading a file, + * retrieving playback progress, and so on. + * + * These are documented elsewhere: + * * http://mpv.io/manual/master/#options + * * http://mpv.io/manual/master/#list-of-input-commands + * * http://mpv.io/manual/master/#properties + * + * You can also look at the examples here: + * * https://github.com/mpv-player/mpv-examples/tree/master/libmpv + * + * Event loop + * ---------- + * + * In general, the API user should run an event loop in order to receive events. + * This event loop should call mpv_wait_event(), which will return once a new + * mpv client API is available. It is also possible to integrate client API + * usage in other event loops (e.g. GUI toolkits) with the + * mpv_set_wakeup_callback() function, and then polling for events by calling + * mpv_wait_event() with a 0 timeout. + * + * Note that the event loop is detached from the actual player. Not calling + * mpv_wait_event() will not stop playback. It will eventually congest the + * event queue of your API handle, though. + * + * Synchronous vs. asynchronous calls + * ---------------------------------- + * + * The API allows both synchronous and asynchronous calls. Synchronous calls + * have to wait until the playback core is ready, which currently can take + * an unbounded time (e.g. if network is slow or unresponsive). Asynchronous + * calls just queue operations as requests, and return the result of the + * operation as events. + * + * Asynchronous calls + * ------------------ + * + * The client API includes asynchronous functions. These allow you to send + * requests instantly, and get replies as events at a later point. The + * requests are made with functions carrying the _async suffix, and replies + * are returned by mpv_wait_event() (interleaved with the normal event stream). + * + * A 64 bit userdata value is used to allow the user to associate requests + * with replies. The value is passed as reply_userdata parameter to the request + * function. The reply to the request will have the reply + * mpv_event->reply_userdata field set to the same value as the + * reply_userdata parameter of the corresponding request. + * + * This userdata value is arbitrary and is never interpreted by the API. Note + * that the userdata value 0 is also allowed, but then the client must be + * careful not accidentally interpret the mpv_event->reply_userdata if an + * event is not a reply. (For non-replies, this field is set to 0.) + * + * Asynchronous calls may be reordered in arbitrarily with other synchronous + * and asynchronous calls. If you want a guaranteed order, you need to wait + * until asynchronous calls report completion before doing the next call. + * + * See also the section "Asynchronous command details" in the manpage. + * + * Multithreading + * -------------- + * + * The client API is generally fully thread-safe, unless otherwise noted. + * Currently, there is no real advantage in using more than 1 thread to access + * the client API, since everything is serialized through a single lock in the + * playback core. + * + * Basic environment requirements + * ------------------------------ + * + * This documents basic requirements on the C environment. This is especially + * important if mpv is used as library with mpv_create(). + * + * - The LC_NUMERIC locale category must be set to "C". If your program calls + * setlocale(), be sure not to use LC_ALL, or if you do, reset LC_NUMERIC + * to its sane default: setlocale(LC_NUMERIC, "C"). + * - If a X11 based VO is used, mpv will set the xlib error handler. This error + * handler is process-wide, and there's no proper way to share it with other + * xlib users within the same process. This might confuse GUI toolkits. + * - mpv uses some other libraries that are not library-safe, such as Fribidi + * (used through libass), ALSA, FFmpeg, and possibly more. + * - The FPU precision must be set at least to double precision. + * - On Windows, mpv will call timeBeginPeriod(1). + * - On memory exhaustion, mpv will kill the process. + * - In certain cases, mpv may start sub processes (such as with the ytdl + * wrapper script). + * - Using UNIX IPC (off by default) will override the SIGPIPE signal handler, + * and set it to SIG_IGN. Some invocations of the "subprocess" command will + * also do that. + * - mpv may start sub processes, so overriding SIGCHLD, or waiting on all PIDs + * (such as calling wait()) by the parent process or any other library within + * the process must be avoided. libmpv itself only waits for its own PIDs. + * - If anything in the process registers signal handlers, they must set the + * SA_RESTART flag. Otherwise you WILL get random failures on signals. + * + * Encoding of filenames + * --------------------- + * + * mpv uses UTF-8 everywhere. + * + * On some platforms (like Linux), filenames actually do not have to be UTF-8; + * for this reason libmpv supports non-UTF-8 strings. libmpv uses what the + * kernel uses and does not recode filenames. At least on Linux, passing a + * string to libmpv is like passing a string to the fopen() function. + * + * On Windows, filenames are always UTF-8, libmpv converts between UTF-8 and + * UTF-16 when using win32 API functions. libmpv never uses or accepts + * filenames in the local 8 bit encoding. It does not use fopen() either; + * it uses _wfopen(). + * + * On macOS, filenames and other strings taken/returned by libmpv can have + * inconsistent unicode normalization. This can sometimes lead to problems. + * You have to hope for the best. + * + * Also see the remarks for MPV_FORMAT_STRING. + * + * Embedding the video window + * -------------------------- + * + * Using the render API (in render.h) is recommended. This API requires + * you to create and maintain an OpenGL context, to which you can render + * video using a specific API call. This API does not include keyboard or mouse + * input directly. + * + * There is an older way to embed the native mpv window into your own. You have + * to get the raw window handle, and set it as "wid" option. This works on X11, + * win32, and macOS only. It's much easier to use than the render API, but + * also has various problems. + * + * Also see client API examples and the mpv manpage. There is an extensive + * discussion here: + * https://github.com/mpv-player/mpv-examples/tree/master/libmpv#methods-of-embedding-the-video-window + * + * Compatibility + * ------------- + * + * mpv development doesn't stand still, and changes to mpv internals as well as + * to its interface can cause compatibility issues to client API users. + * + * The API is versioned (see MPV_CLIENT_API_VERSION), and changes to it are + * documented in DOCS/client-api-changes.rst. The C API itself will probably + * remain compatible for a long time, but the functionality exposed by it + * could change more rapidly. For example, it's possible that options are + * renamed, or change the set of allowed values. + * + * Defensive programming should be used to potentially deal with the fact that + * options, commands, and properties could disappear, change their value range, + * or change the underlying datatypes. It might be a good idea to prefer + * MPV_FORMAT_STRING over other types to decouple your code from potential + * mpv changes. + * + * Also see: DOCS/compatibility.rst + * + * Future changes + * -------------- + * + * This are the planned changes that will most likely be done on the next major + * bump of the library: + * + * - remove all symbols that are marked as deprecated + * - reassign enum numerical values to remove gaps + * - disabling all events by default + */ + +/** + * The version is incremented on each API change. The 16 lower bits form the + * minor version number, and the 16 higher bits the major version number. If + * the API becomes incompatible to previous versions, the major version + * number is incremented. This affects only C part, and not properties and + * options. + * + * Every API bump is described in DOCS/client-api-changes.rst + * + * You can use MPV_MAKE_VERSION() and compare the result with integer + * relational operators (<, >, <=, >=). + */ +#define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL) +#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(2, 6) + +/** + * The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before + * including any libmpv headers. Then deprecated symbols will be excluded + * from the headers. (Of course, deprecated properties and commands and + * other functionality will still work.) + */ +#ifndef MPV_ENABLE_DEPRECATED +#define MPV_ENABLE_DEPRECATED 1 +#endif + +/** + * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with. + */ +MPV_EXPORT unsigned long mpv_client_api_version(void); + +/** + * Client context used by the client API. Every client has its own private + * handle. + */ +typedef struct mpv_handle mpv_handle; + +/** + * List of error codes than can be returned by API functions. 0 and positive + * return values always mean success, negative values are always errors. + */ +typedef enum mpv_error { + /** + * No error happened (used to signal successful operation). + * Keep in mind that many API functions returning error codes can also + * return positive values, which also indicate success. API users can + * hardcode the fact that ">= 0" means success. + */ + MPV_ERROR_SUCCESS = 0, + /** + * The event ringbuffer is full. This means the client is choked, and can't + * receive any events. This can happen when too many asynchronous requests + * have been made, but not answered. Probably never happens in practice, + * unless the mpv core is frozen for some reason, and the client keeps + * making asynchronous requests. (Bugs in the client API implementation + * could also trigger this, e.g. if events become "lost".) + */ + MPV_ERROR_EVENT_QUEUE_FULL = -1, + /** + * Memory allocation failed. + */ + MPV_ERROR_NOMEM = -2, + /** + * The mpv core wasn't configured and initialized yet. See the notes in + * mpv_create(). + */ + MPV_ERROR_UNINITIALIZED = -3, + /** + * Generic catch-all error if a parameter is set to an invalid or + * unsupported value. This is used if there is no better error code. + */ + MPV_ERROR_INVALID_PARAMETER = -4, + /** + * Trying to set an option that doesn't exist. + */ + MPV_ERROR_OPTION_NOT_FOUND = -5, + /** + * Trying to set an option using an unsupported MPV_FORMAT. + */ + MPV_ERROR_OPTION_FORMAT = -6, + /** + * Setting the option failed. Typically this happens if the provided option + * value could not be parsed. + */ + MPV_ERROR_OPTION_ERROR = -7, + /** + * The accessed property doesn't exist. + */ + MPV_ERROR_PROPERTY_NOT_FOUND = -8, + /** + * Trying to set or get a property using an unsupported MPV_FORMAT. + */ + MPV_ERROR_PROPERTY_FORMAT = -9, + /** + * The property exists, but is not available. This usually happens when the + * associated subsystem is not active, e.g. querying audio parameters while + * audio is disabled. + */ + MPV_ERROR_PROPERTY_UNAVAILABLE = -10, + /** + * Error setting or getting a property. + */ + MPV_ERROR_PROPERTY_ERROR = -11, + /** + * General error when running a command with mpv_command and similar. + */ + MPV_ERROR_COMMAND = -12, + /** + * Generic error on loading (usually used with mpv_event_end_file.error). + */ + MPV_ERROR_LOADING_FAILED = -13, + /** + * Initializing the audio output failed. + */ + MPV_ERROR_AO_INIT_FAILED = -14, + /** + * Initializing the video output failed. + */ + MPV_ERROR_VO_INIT_FAILED = -15, + /** + * There was no audio or video data to play. This also happens if the + * file was recognized, but did not contain any audio or video streams, + * or no streams were selected. + */ + MPV_ERROR_NOTHING_TO_PLAY = -16, + /** + * When trying to load the file, the file format could not be determined, + * or the file was too broken to open it. + */ + MPV_ERROR_UNKNOWN_FORMAT = -17, + /** + * Generic error for signaling that certain system requirements are not + * fulfilled. + */ + MPV_ERROR_UNSUPPORTED = -18, + /** + * The API function which was called is a stub only. + */ + MPV_ERROR_NOT_IMPLEMENTED = -19, + /** + * Unspecified error. + */ + MPV_ERROR_GENERIC = -20 +} mpv_error; + +/** + * Return a string describing the error. For unknown errors, the string + * "unknown error" is returned. + * + * @param error error number, see enum mpv_error + * @return A static string describing the error. The string is completely + * static, i.e. doesn't need to be deallocated, and is valid forever. + */ +MPV_EXPORT const char *mpv_error_string(int error); + +/** + * General function to deallocate memory returned by some of the API functions. + * Call this only if it's explicitly documented as allowed. Calling this on + * mpv memory not owned by the caller will lead to undefined behavior. + * + * @param data A valid pointer returned by the API, or NULL. + */ +MPV_EXPORT void mpv_free(void *data); + +/** + * Return the name of this client handle. Every client has its own unique + * name, which is mostly used for user interface purposes. + * + * @return The client name. The string is read-only and is valid until the + * mpv_handle is destroyed. + */ +MPV_EXPORT const char *mpv_client_name(mpv_handle *ctx); + +/** + * Return the ID of this client handle. Every client has its own unique ID. This + * ID is never reused by the core, even if the mpv_handle at hand gets destroyed + * and new handles get allocated. + * + * IDs are never 0 or negative. + * + * Some mpv APIs (not necessarily all) accept a name in the form "@" in + * addition of the proper mpv_client_name(), where "" is the ID in decimal + * form (e.g. "@123"). For example, the "script-message-to" command takes the + * client name as first argument, but also accepts the client ID formatted in + * this manner. + * + * @return The client ID. + */ +MPV_EXPORT int64_t mpv_client_id(mpv_handle *ctx); + +/** + * Create a new mpv instance and an associated client API handle to control + * the mpv instance. This instance is in a pre-initialized state, + * and needs to be initialized to be actually used with most other API + * functions. + * + * Some API functions will return MPV_ERROR_UNINITIALIZED in the uninitialized + * state. You can call mpv_set_property() (or mpv_set_property_string() and + * other variants, and before mpv 0.21.0 mpv_set_option() etc.) to set initial + * options. After this, call mpv_initialize() to start the player, and then use + * e.g. mpv_command() to start playback of a file. + * + * The point of separating handle creation and actual initialization is that + * you can configure things which can't be changed during runtime. + * + * Unlike the command line player, this will have initial settings suitable + * for embedding in applications. The following settings are different: + * - stdin/stdout/stderr and the terminal will never be accessed. This is + * equivalent to setting the --no-terminal option. + * (Technically, this also suppresses C signal handling.) + * - No config files will be loaded. This is roughly equivalent to using + * --config=no. Since libmpv 1.15, you can actually re-enable this option, + * which will make libmpv load config files during mpv_initialize(). If you + * do this, you are strongly encouraged to set the "config-dir" option too. + * (Otherwise it will load the mpv command line player's config.) + * For example: + * mpv_set_option_string(mpv, "config-dir", "/my/path"); // set config root + * mpv_set_option_string(mpv, "config", "yes"); // enable config loading + * (call mpv_initialize() _after_ this) + * - Idle mode is enabled, which means the playback core will enter idle mode + * if there are no more files to play on the internal playlist, instead of + * exiting. This is equivalent to the --idle option. + * - Disable parts of input handling. + * - Most of the different settings can be viewed with the command line player + * by running "mpv --show-profile=libmpv". + * + * All this assumes that API users want a mpv instance that is strictly + * isolated from the command line player's configuration, user settings, and + * so on. You can re-enable disabled features by setting the appropriate + * options. + * + * The mpv command line parser is not available through this API, but you can + * set individual options with mpv_set_property(). Files for playback must be + * loaded with mpv_command() or others. + * + * Note that you should avoid doing concurrent accesses on the uninitialized + * client handle. (Whether concurrent access is definitely allowed or not has + * yet to be decided.) + * + * @return a new mpv client API handle. Returns NULL on error. Currently, this + * can happen in the following situations: + * - out of memory + * - LC_NUMERIC is not set to "C" (see general remarks) + */ +MPV_EXPORT mpv_handle *mpv_create(void); + +/** + * Initialize an uninitialized mpv instance. If the mpv instance is already + * running, an error is returned. + * + * This function needs to be called to make full use of the client API if the + * client API handle was created with mpv_create(). + * + * Only the following options are required to be set _before_ mpv_initialize(): + * - options which are only read at initialization time: + * - config + * - config-dir + * - input-conf + * - load-scripts + * - script + * - player-operation-mode + * - input-app-events (macOS) + * - all encoding mode options + * + * @return error code + */ +MPV_EXPORT int mpv_initialize(mpv_handle *ctx); + +/** + * Disconnect and destroy the mpv_handle. ctx will be deallocated with this + * API call. + * + * If the last mpv_handle is detached, the core player is destroyed. In + * addition, if there are only weak mpv_handles (such as created by + * mpv_create_weak_client() or internal scripts), these mpv_handles will + * be sent MPV_EVENT_SHUTDOWN. This function may block until these clients + * have responded to the shutdown event, and the core is finally destroyed. + */ +MPV_EXPORT void mpv_destroy(mpv_handle *ctx); + +/** + * Similar to mpv_destroy(), but brings the player and all clients down + * as well, and waits until all of them are destroyed. This function blocks. The + * advantage over mpv_destroy() is that while mpv_destroy() merely + * detaches the client handle from the player, this function quits the player, + * waits until all other clients are destroyed (i.e. all mpv_handles are + * detached), and also waits for the final termination of the player. + * + * Since mpv_destroy() is called somewhere on the way, it's not safe to + * call other functions concurrently on the same context. + * + * Since mpv client API version 1.29: + * The first call on any mpv_handle will block until the core is destroyed. + * This means it will wait until other mpv_handle have been destroyed. If you + * want asynchronous destruction, just run the "quit" command, and then react + * to the MPV_EVENT_SHUTDOWN event. + * If another mpv_handle already called mpv_terminate_destroy(), this call will + * not actually block. It will destroy the mpv_handle, and exit immediately, + * while other mpv_handles might still be uninitializing. + * + * Before mpv client API version 1.29: + * If this is called on a mpv_handle that was not created with mpv_create(), + * this function will merely send a quit command and then call + * mpv_destroy(), without waiting for the actual shutdown. + */ +MPV_EXPORT void mpv_terminate_destroy(mpv_handle *ctx); + +/** + * Create a new client handle connected to the same player core as ctx. This + * context has its own event queue, its own mpv_request_event() state, its own + * mpv_request_log_messages() state, its own set of observed properties, and + * its own state for asynchronous operations. Otherwise, everything is shared. + * + * This handle should be destroyed with mpv_destroy() if no longer + * needed. The core will live as long as there is at least 1 handle referencing + * it. Any handle can make the core quit, which will result in every handle + * receiving MPV_EVENT_SHUTDOWN. + * + * This function can not be called before the main handle was initialized with + * mpv_initialize(). The new handle is always initialized, unless ctx=NULL was + * passed. + * + * @param ctx Used to get the reference to the mpv core; handle-specific + * settings and parameters are not used. + * If NULL, this function behaves like mpv_create() (ignores name). + * @param name The client name. This will be returned by mpv_client_name(). If + * the name is already in use, or contains non-alphanumeric + * characters (other than '_'), the name is modified to fit. + * If NULL, an arbitrary name is automatically chosen. + * @return a new handle, or NULL on error + */ +MPV_EXPORT mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name); + +/** + * This is the same as mpv_create_client(), but the created mpv_handle is + * treated as a weak reference. If all mpv_handles referencing a core are + * weak references, the core is automatically destroyed. (This still goes + * through normal uninit of course. Effectively, if the last non-weak mpv_handle + * is destroyed, then the weak mpv_handles receive MPV_EVENT_SHUTDOWN and are + * asked to terminate as well.) + * + * Note if you want to use this like refcounting: you have to be aware that + * mpv_terminate_destroy() _and_ mpv_destroy() for the last non-weak + * mpv_handle will block until all weak mpv_handles are destroyed. + */ +MPV_EXPORT mpv_handle *mpv_create_weak_client(mpv_handle *ctx, const char *name); + +/** + * Load a config file. This loads and parses the file, and sets every entry in + * the config file's default section as if mpv_set_option_string() is called. + * + * The filename should be an absolute path. If it isn't, the actual path used + * is unspecified. (Note: an absolute path starts with '/' on UNIX.) If the + * file wasn't found, MPV_ERROR_INVALID_PARAMETER is returned. + * + * If a fatal error happens when parsing a config file, MPV_ERROR_OPTION_ERROR + * is returned. Errors when setting options as well as other types or errors + * are ignored (even if options do not exist). You can still try to capture + * the resulting error messages with mpv_request_log_messages(). Note that it's + * possible that some options were successfully set even if any of these errors + * happen. + * + * @param filename absolute path to the config file on the local filesystem + * @return error code + */ +MPV_EXPORT int mpv_load_config_file(mpv_handle *ctx, const char *filename); + +/** + * Return the internal time in nanoseconds. This has an arbitrary start offset, + * but will never wrap or go backwards. + * + * Note that this is always the real time, and doesn't necessarily have to do + * with playback time. For example, playback could go faster or slower due to + * playback speed, or due to playback being paused. Use the "time-pos" property + * instead to get the playback status. + * + * Unlike other libmpv APIs, this can be called at absolutely any time (even + * within wakeup callbacks), as long as the context is valid. + * + * Safe to be called from mpv render API threads. + */ +MPV_EXPORT int64_t mpv_get_time_ns(mpv_handle *ctx); + +/** + * Same as mpv_get_time_ns but in microseconds. + */ +MPV_EXPORT int64_t mpv_get_time_us(mpv_handle *ctx); + +/** + * Data format for options and properties. The API functions to get/set + * properties and options support multiple formats, and this enum describes + * them. + */ +typedef enum mpv_format { + /** + * Invalid. Sometimes used for empty values. This is always defined to 0, + * so a normal 0-init of mpv_format (or e.g. mpv_node) is guaranteed to set + * this it to MPV_FORMAT_NONE (which makes some things saner as consequence). + */ + MPV_FORMAT_NONE = 0, + /** + * The basic type is char*. It returns the raw property string, like + * using ${=property} in input.conf (see input.rst). + * + * NULL isn't an allowed value. + * + * Warning: although the encoding is usually UTF-8, this is not always the + * case. File tags often store strings in some legacy codepage, + * and even filenames don't necessarily have to be in UTF-8 (at + * least on Linux). If you pass the strings to code that requires + * valid UTF-8, you have to sanitize it in some way. + * On Windows, filenames are always UTF-8, and libmpv converts + * between UTF-8 and UTF-16 when using win32 API functions. See + * the "Encoding of filenames" section for details. + * + * Example for reading: + * + * char *result = NULL; + * if (mpv_get_property(ctx, "property", MPV_FORMAT_STRING, &result) < 0) + * goto error; + * printf("%s\n", result); + * mpv_free(result); + * + * Or just use mpv_get_property_string(). + * + * Example for writing: + * + * char *value = "the new value"; + * // yep, you pass the address to the variable + * // (needed for symmetry with other types and mpv_get_property) + * mpv_set_property(ctx, "property", MPV_FORMAT_STRING, &value); + * + * Or just use mpv_set_property_string(). + * + */ + MPV_FORMAT_STRING = 1, + /** + * The basic type is char*. It returns the OSD property string, like + * using ${property} in input.conf (see input.rst). In many cases, this + * is the same as the raw string, but in other cases it's formatted for + * display on OSD. It's intended to be human readable. Do not attempt to + * parse these strings. + * + * Only valid when doing read access. The rest works like MPV_FORMAT_STRING. + */ + MPV_FORMAT_OSD_STRING = 2, + /** + * The basic type is int. The only allowed values are 0 ("no") + * and 1 ("yes"). + * + * Example for reading: + * + * int result; + * if (mpv_get_property(ctx, "property", MPV_FORMAT_FLAG, &result) < 0) + * goto error; + * printf("%s\n", result ? "true" : "false"); + * + * Example for writing: + * + * int flag = 1; + * mpv_set_property(ctx, "property", MPV_FORMAT_FLAG, &flag); + */ + MPV_FORMAT_FLAG = 3, + /** + * The basic type is int64_t. + */ + MPV_FORMAT_INT64 = 4, + /** + * The basic type is double. + */ + MPV_FORMAT_DOUBLE = 5, + /** + * The type is mpv_node. + * + * For reading, you usually would pass a pointer to a stack-allocated + * mpv_node value to mpv, and when you're done you call + * mpv_free_node_contents(&node). + * You're expected not to write to the data - if you have to, copy it + * first (which you have to do manually). + * + * For writing, you construct your own mpv_node, and pass a pointer to the + * API. The API will never write to your data (and copy it if needed), so + * you're free to use any form of allocation or memory management you like. + * + * Warning: when reading, always check the mpv_node.format member. For + * example, properties might change their type in future versions + * of mpv, or sometimes even during runtime. + * + * Example for reading: + * + * mpv_node result; + * if (mpv_get_property(ctx, "property", MPV_FORMAT_NODE, &result) < 0) + * goto error; + * printf("format=%d\n", (int)result.format); + * mpv_free_node_contents(&result). + * + * Example for writing: + * + * mpv_node value; + * value.format = MPV_FORMAT_STRING; + * value.u.string = "hello"; + * mpv_set_property(ctx, "property", MPV_FORMAT_NODE, &value); + */ + MPV_FORMAT_NODE = 6, + /** + * Used with mpv_node only. Can usually not be used directly. + */ + MPV_FORMAT_NODE_ARRAY = 7, + /** + * See MPV_FORMAT_NODE_ARRAY. + */ + MPV_FORMAT_NODE_MAP = 8, + /** + * A raw, untyped byte array. Only used only with mpv_node, and only in + * some very specific situations. (Some commands use it.) + */ + MPV_FORMAT_BYTE_ARRAY = 9 +} mpv_format; + +/** + * Generic data storage. + * + * If mpv writes this struct (e.g. via mpv_get_property()), you must not change + * the data. In some cases (mpv_get_property()), you have to free it with + * mpv_free_node_contents(). If you fill this struct yourself, you're also + * responsible for freeing it, and you must not call mpv_free_node_contents(). + */ +typedef struct mpv_node { + union { + char *string; /** valid if format==MPV_FORMAT_STRING */ + int flag; /** valid if format==MPV_FORMAT_FLAG */ + int64_t int64; /** valid if format==MPV_FORMAT_INT64 */ + double double_; /** valid if format==MPV_FORMAT_DOUBLE */ + /** + * valid if format==MPV_FORMAT_NODE_ARRAY + * or if format==MPV_FORMAT_NODE_MAP + */ + struct mpv_node_list *list; + /** + * valid if format==MPV_FORMAT_BYTE_ARRAY + */ + struct mpv_byte_array *ba; + } u; + /** + * Type of the data stored in this struct. This value rules what members in + * the given union can be accessed. The following formats are currently + * defined to be allowed in mpv_node: + * + * MPV_FORMAT_STRING (u.string) + * MPV_FORMAT_FLAG (u.flag) + * MPV_FORMAT_INT64 (u.int64) + * MPV_FORMAT_DOUBLE (u.double_) + * MPV_FORMAT_NODE_ARRAY (u.list) + * MPV_FORMAT_NODE_MAP (u.list) + * MPV_FORMAT_BYTE_ARRAY (u.ba) + * MPV_FORMAT_NONE (no member) + * + * If you encounter a value you don't know, you must not make any + * assumptions about the contents of union u. + */ + mpv_format format; +} mpv_node; + +/** + * (see mpv_node) + */ +typedef struct mpv_node_list { + /** + * Number of entries. Negative values are not allowed. + */ + int num; + /** + * MPV_FORMAT_NODE_ARRAY: + * values[N] refers to value of the Nth item + * + * MPV_FORMAT_NODE_MAP: + * values[N] refers to value of the Nth key/value pair + * + * If num > 0, values[0] to values[num-1] (inclusive) are valid. + * Otherwise, this can be NULL. + */ + mpv_node *values; + /** + * MPV_FORMAT_NODE_ARRAY: + * unused (typically NULL), access is not allowed + * + * MPV_FORMAT_NODE_MAP: + * keys[N] refers to key of the Nth key/value pair. If num > 0, keys[0] to + * keys[num-1] (inclusive) are valid. Otherwise, this can be NULL. + * The keys are in random order. The only guarantee is that keys[N] belongs + * to the value values[N]. NULL keys are not allowed. + */ + char **keys; +} mpv_node_list; + +/** + * (see mpv_node) + */ +typedef struct mpv_byte_array { + /** + * Pointer to the data. In what format the data is stored is up to whatever + * uses MPV_FORMAT_BYTE_ARRAY. + */ + void *data; + /** + * Size of the data pointed to by ptr. + */ + size_t size; +} mpv_byte_array; + +/** + * Frees any data referenced by the node. It doesn't free the node itself. + * Call this only if the mpv client API set the node. If you constructed the + * node yourself (manually), you have to free it yourself. + * + * If node->format is MPV_FORMAT_NONE, this call does nothing. Likewise, if + * the client API sets a node with this format, this function doesn't need to + * be called. (This is just a clarification that there's no danger of anything + * strange happening in these cases.) + */ +MPV_EXPORT void mpv_free_node_contents(mpv_node *node); + +/** + * Set an option. Note that you can't normally set options during runtime. It + * works in uninitialized state (see mpv_create()), and in some cases in at + * runtime. + * + * Using a format other than MPV_FORMAT_NODE is equivalent to constructing a + * mpv_node with the given format and data, and passing the mpv_node to this + * function. + * + * Note: this is semi-deprecated. For most purposes, this is not needed anymore. + * Starting with mpv version 0.21.0 (version 1.23) most options can be set + * with mpv_set_property() (and related functions), and even before + * mpv_initialize(). In some obscure corner cases, using this function + * to set options might still be required (see + * "Inconsistencies between options and properties" in the manpage). Once + * these are resolved, the option setting functions might be fully + * deprecated. + * + * @param name Option name. This is the same as on the mpv command line, but + * without the leading "--". + * @param format see enum mpv_format. + * @param[in] data Option value (according to the format). + * @return error code + */ +MPV_EXPORT int mpv_set_option(mpv_handle *ctx, const char *name, mpv_format format, + void *data); + +/** + * Convenience function to set an option to a string value. This is like + * calling mpv_set_option() with MPV_FORMAT_STRING. + * + * @return error code + */ +MPV_EXPORT int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data); + +/** + * Send a command to the player. Commands are the same as those used in + * input.conf, except that this function takes parameters in a pre-split + * form. + * + * The commands and their parameters are documented in input.rst. + * + * Does not use OSD and string expansion by default (unlike mpv_command_string() + * and input.conf). + * + * @param[in] args NULL-terminated list of strings. Usually, the first item + * is the command, and the following items are arguments. + * @return error code + */ +MPV_EXPORT int mpv_command(mpv_handle *ctx, const char **args); + +/** + * Same as mpv_command(), but allows passing structured data in any format. + * In particular, calling mpv_command() is exactly like calling + * mpv_command_node() with the format set to MPV_FORMAT_NODE_ARRAY, and + * every arg passed in order as MPV_FORMAT_STRING. + * + * Does not use OSD and string expansion by default. + * + * The args argument can have one of the following formats: + * + * MPV_FORMAT_NODE_ARRAY: + * Positional arguments. Each entry is an argument using an arbitrary + * format (the format must be compatible to the used command). Usually, + * the first item is the command name (as MPV_FORMAT_STRING). The order + * of arguments is as documented in each command description. + * + * MPV_FORMAT_NODE_MAP: + * Named arguments. This requires at least a special entry with the key + * "_name" to be present, which must be a string, and contains the command + * name. For compatibility, if the key "_name" does not exist, then the + * entry with the key "name" will be used instead. + * The special entry "_flags" is optional, and if present, must be an + * array of strings, each being a command prefix to apply. All other + * entries are interpreted as arguments. They must use the argument names + * as documented in each command description. Some commands do not + * support named arguments at all, and must use MPV_FORMAT_NODE_ARRAY. + * Some commands have arguments named "name", and can only be used if + * the command name is specified with key "_name" instead of "name". + * + * @param[in] args mpv_node with format set to one of the values documented + * above (see there for details) + * @param[out] result Optional, pass NULL if unused. If not NULL, and if the + * function succeeds, this is set to command-specific return + * data. You must call mpv_free_node_contents() to free it + * (again, only if the command actually succeeds). + * Not many commands actually use this at all. + * @return error code (the result parameter is not set on error) + */ +MPV_EXPORT int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result); + +/** + * This is essentially identical to mpv_command() but it also returns a result. + * + * Does not use OSD and string expansion by default. + * + * @param[in] args NULL-terminated list of strings. Usually, the first item + * is the command, and the following items are arguments. + * @param[out] result Optional, pass NULL if unused. If not NULL, and if the + * function succeeds, this is set to command-specific return + * data. You must call mpv_free_node_contents() to free it + * (again, only if the command actually succeeds). + * Not many commands actually use this at all. + * @return error code (the result parameter is not set on error) + */ +MPV_EXPORT int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result); + +/** + * Same as mpv_command, but use input.conf parsing for splitting arguments. + * This is slightly simpler, but also more error prone, since arguments may + * need quoting/escaping. + * + * This also has OSD and string expansion enabled by default. + */ +MPV_EXPORT int mpv_command_string(mpv_handle *ctx, const char *args); + +/** + * Same as mpv_command, but run the command asynchronously. + * + * Commands are executed asynchronously. You will receive a + * MPV_EVENT_COMMAND_REPLY event. This event will also have an + * error code set if running the command failed. For commands that + * return data, the data is put into mpv_event_command.result. + * + * The only case when you do not receive an event is when the function call + * itself fails. This happens only if parsing the command itself (or otherwise + * validating it) fails, i.e. the return code of the API call is not 0 or + * positive. + * + * Safe to be called from mpv render API threads. + * + * @param reply_userdata the value mpv_event.reply_userdata of the reply will + * be set to (see section about asynchronous calls) + * @param args NULL-terminated list of strings (see mpv_command()) + * @return error code (if parsing or queuing the command fails) + */ +MPV_EXPORT int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, + const char **args); + +/** + * Same as mpv_command_node(), but run it asynchronously. Basically, this + * function is to mpv_command_node() what mpv_command_async() is to + * mpv_command(). + * + * See mpv_command_async() for details. + * + * Safe to be called from mpv render API threads. + * + * @param reply_userdata the value mpv_event.reply_userdata of the reply will + * be set to (see section about asynchronous calls) + * @param args as in mpv_command_node() + * @return error code (if parsing or queuing the command fails) + */ +MPV_EXPORT int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, + mpv_node *args); + +/** + * Signal to all async requests with the matching ID to abort. This affects + * the following API calls: + * + * mpv_command_async + * mpv_command_node_async + * + * All of these functions take a reply_userdata parameter. This API function + * tells all requests with the matching reply_userdata value to try to return + * as soon as possible. If there are multiple requests with matching ID, it + * aborts all of them. + * + * This API function is mostly asynchronous itself. It will not wait until the + * command is aborted. Instead, the command will terminate as usual, but with + * some work not done. How this is signaled depends on the specific command (for + * example, the "subprocess" command will indicate it by "killed_by_us" set to + * true in the result). How long it takes also depends on the situation. The + * aborting process is completely asynchronous. + * + * Not all commands may support this functionality. In this case, this function + * will have no effect. The same is true if the request using the passed + * reply_userdata has already terminated, has not been started yet, or was + * never in use at all. + * + * You have to be careful of race conditions: the time during which the abort + * request will be effective is _after_ e.g. mpv_command_async() has returned, + * and before the command has signaled completion with MPV_EVENT_COMMAND_REPLY. + * + * @param reply_userdata ID of the request to be aborted (see above) + */ +MPV_EXPORT void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata); + +/** + * Set a property to a given value. Properties are essentially variables which + * can be queried or set at runtime. For example, writing to the pause property + * will actually pause or unpause playback. + * + * If the format doesn't match with the internal format of the property, access + * usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data + * is automatically converted and access succeeds. For example, MPV_FORMAT_INT64 + * is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING + * usually invokes a string parser. The same happens when calling this function + * with MPV_FORMAT_NODE: the underlying format may be converted to another + * type if possible. + * + * Using a format other than MPV_FORMAT_NODE is equivalent to constructing a + * mpv_node with the given format and data, and passing the mpv_node to this + * function. (Before API version 1.21, this was different.) + * + * Note: starting with mpv 0.21.0 (client API version 1.23), this can be used to + * set options in general. It even can be used before mpv_initialize() + * has been called. If called before mpv_initialize(), setting properties + * not backed by options will result in MPV_ERROR_PROPERTY_UNAVAILABLE. + * In some cases, properties and options still conflict. In these cases, + * mpv_set_property() accesses the options before mpv_initialize(), and + * the properties after mpv_initialize(). These conflicts will be removed + * in mpv 0.23.0. See mpv_set_option() for further remarks. + * + * @param name The property name. See input.rst for a list of properties. + * @param format see enum mpv_format. + * @param[in] data Option value. + * @return error code + */ +MPV_EXPORT int mpv_set_property(mpv_handle *ctx, const char *name, mpv_format format, + void *data); + +/** + * Convenience function to set a property to a string value. + * + * This is like calling mpv_set_property() with MPV_FORMAT_STRING. + */ +MPV_EXPORT int mpv_set_property_string(mpv_handle *ctx, const char *name, const char *data); + +/** + * Convenience function to delete a property. + * + * This is equivalent to running the command "del [name]". + * + * @param name The property name. See input.rst for a list of properties. + * @return error code + */ +MPV_EXPORT int mpv_del_property(mpv_handle *ctx, const char *name); + +/** + * Set a property asynchronously. You will receive the result of the operation + * as MPV_EVENT_SET_PROPERTY_REPLY event. The mpv_event.error field will contain + * the result status of the operation. Otherwise, this function is similar to + * mpv_set_property(). + * + * Safe to be called from mpv render API threads. + * + * @param reply_userdata see section about asynchronous calls + * @param name The property name. + * @param format see enum mpv_format. + * @param[in] data Option value. The value will be copied by the function. It + * will never be modified by the client API. + * @return error code if sending the request failed + */ +MPV_EXPORT int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata, + const char *name, mpv_format format, void *data); + +/** + * Read the value of the given property. + * + * If the format doesn't match with the internal format of the property, access + * usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data + * is automatically converted and access succeeds. For example, MPV_FORMAT_INT64 + * is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING + * usually invokes a string formatter. + * + * @param name The property name. + * @param format see enum mpv_format. + * @param[out] data Pointer to the variable holding the option value. On + * success, the variable will be set to a copy of the option + * value. For formats that require dynamic memory allocation, + * you can free the value with mpv_free() (strings) or + * mpv_free_node_contents() (MPV_FORMAT_NODE). + * @return error code + */ +MPV_EXPORT int mpv_get_property(mpv_handle *ctx, const char *name, mpv_format format, + void *data); + +/** + * Return the value of the property with the given name as string. This is + * equivalent to mpv_get_property() with MPV_FORMAT_STRING. + * + * See MPV_FORMAT_STRING for character encoding issues. + * + * On error, NULL is returned. Use mpv_get_property() if you want fine-grained + * error reporting. + * + * @param name The property name. + * @return Property value, or NULL if the property can't be retrieved. Free + * the string with mpv_free(). + */ +MPV_EXPORT char *mpv_get_property_string(mpv_handle *ctx, const char *name); + +/** + * Return the property as "OSD" formatted string. This is the same as + * mpv_get_property_string, but using MPV_FORMAT_OSD_STRING. + * + * @return Property value, or NULL if the property can't be retrieved. Free + * the string with mpv_free(). + */ +MPV_EXPORT char *mpv_get_property_osd_string(mpv_handle *ctx, const char *name); + +/** + * Get a property asynchronously. You will receive the result of the operation + * as well as the property data with the MPV_EVENT_GET_PROPERTY_REPLY event. + * You should check the mpv_event.error field on the reply event. + * + * Safe to be called from mpv render API threads. + * + * @param reply_userdata see section about asynchronous calls + * @param name The property name. + * @param format see enum mpv_format. + * @return error code if sending the request failed + */ +MPV_EXPORT int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata, + const char *name, mpv_format format); + +/** + * Get a notification whenever the given property changes. You will receive + * updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise: + * for some properties, it may not send updates even if the property changed. + * This depends on the property, and it's a valid feature request to ask for + * better update handling of a specific property. (For some properties, like + * ``clock``, which shows the wall clock, this mechanism doesn't make too + * much sense anyway.) + * + * Property changes are coalesced: the change events are returned only once the + * event queue becomes empty (e.g. mpv_wait_event() would block or return + * MPV_EVENT_NONE), and then only one event per changed property is returned. + * + * You always get an initial change notification. This is meant to initialize + * the user's state to the current value of the property. + * + * Normally, change events are sent only if the property value changes according + * to the requested format. mpv_event_property will contain the property value + * as data member. + * + * Warning: if a property is unavailable or retrieving it caused an error, + * MPV_FORMAT_NONE will be set in mpv_event_property, even if the + * format parameter was set to a different value. In this case, the + * mpv_event_property.data field is invalid. + * + * If the property is observed with the format parameter set to MPV_FORMAT_NONE, + * you get low-level notifications whether the property _may_ have changed, and + * the data member in mpv_event_property will be unset. With this mode, you + * will have to determine yourself whether the property really changed. On the + * other hand, this mechanism can be faster and uses less resources. + * + * Observing a property that doesn't exist is allowed. (Although it may still + * cause some sporadic change events.) + * + * Keep in mind that you will get change notifications even if you change a + * property yourself. Try to avoid endless feedback loops, which could happen + * if you react to the change notifications triggered by your own change. + * + * Only the mpv_handle on which this was called will receive the property + * change events, or can unobserve them. + * + * Safe to be called from mpv render API threads. + * + * @param reply_userdata This will be used for the mpv_event.reply_userdata + * field for the received MPV_EVENT_PROPERTY_CHANGE + * events. (Also see section about asynchronous calls, + * although this function is somewhat different from + * actual asynchronous calls.) + * If you have no use for this, pass 0. + * Also see mpv_unobserve_property(). + * @param name The property name. + * @param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values + * from the change events. + * @return error code (usually fails only on OOM or unsupported format) + */ +MPV_EXPORT int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata, + const char *name, mpv_format format); + +/** + * Undo mpv_observe_property(). This will remove all observed properties for + * which the given number was passed as reply_userdata to mpv_observe_property. + * + * Safe to be called from mpv render API threads. + * + * @param registered_reply_userdata ID that was passed to mpv_observe_property + * @return negative value is an error code, >=0 is number of removed properties + * on success (includes the case when 0 were removed) + */ +MPV_EXPORT int mpv_unobserve_property(mpv_handle *mpv, uint64_t registered_reply_userdata); + +typedef enum mpv_event_id { + /** + * Nothing happened. Happens on timeouts or sporadic wakeups. + */ + MPV_EVENT_NONE = 0, + /** + * Happens when the player quits. The player enters a state where it tries + * to disconnect all clients. Most requests to the player will fail, and + * the client should react to this and quit with mpv_destroy() as soon as + * possible. + */ + MPV_EVENT_SHUTDOWN = 1, + /** + * See mpv_request_log_messages(). + */ + MPV_EVENT_LOG_MESSAGE = 2, + /** + * Reply to a mpv_get_property_async() request. + * See also mpv_event and mpv_event_property. + */ + MPV_EVENT_GET_PROPERTY_REPLY = 3, + /** + * Reply to a mpv_set_property_async() request. + * (Unlike MPV_EVENT_GET_PROPERTY, mpv_event_property is not used.) + */ + MPV_EVENT_SET_PROPERTY_REPLY = 4, + /** + * Reply to a mpv_command_async() or mpv_command_node_async() request. + * See also mpv_event and mpv_event_command. + */ + MPV_EVENT_COMMAND_REPLY = 5, + /** + * Notification before playback start of a file (before the file is loaded). + * See also mpv_event and mpv_event_start_file. + */ + MPV_EVENT_START_FILE = 6, + /** + * Notification after playback end (after the file was unloaded). + * See also mpv_event and mpv_event_end_file. + */ + MPV_EVENT_END_FILE = 7, + /** + * Notification when the file has been loaded (headers were read etc.), and + * decoding starts. + */ + MPV_EVENT_FILE_LOADED = 8, +#if MPV_ENABLE_DEPRECATED + /** + * Idle mode was entered. In this mode, no file is played, and the playback + * core waits for new commands. (The command line player normally quits + * instead of entering idle mode, unless --idle was specified. If mpv + * was started with mpv_create(), idle mode is enabled by default.) + * + * @deprecated This is equivalent to using mpv_observe_property() on the + * "idle-active" property. The event is redundant, and might be + * removed in the far future. As a further warning, this event + * is not necessarily sent at the right point anymore (at the + * start of the program), while the property behaves correctly. + */ + MPV_EVENT_IDLE = 11, + /** + * Sent every time after a video frame is displayed. Note that currently, + * this will be sent in lower frequency if there is no video, or playback + * is paused - but that will be removed in the future, and it will be + * restricted to video frames only. + * + * @deprecated Use mpv_observe_property() with relevant properties instead + * (such as "playback-time"). + */ + MPV_EVENT_TICK = 14, +#endif + /** + * Triggered by the script-message input command. The command uses the + * first argument of the command as client name (see mpv_client_name()) to + * dispatch the message, and passes along all arguments starting from the + * second argument as strings. + * See also mpv_event and mpv_event_client_message. + */ + MPV_EVENT_CLIENT_MESSAGE = 16, + /** + * Happens after video changed in some way. This can happen on resolution + * changes, pixel format changes, or video filter changes. The event is + * sent after the video filters and the VO are reconfigured. Applications + * embedding a mpv window should listen to this event in order to resize + * the window if needed. + * Note that this event can happen sporadically, and you should check + * yourself whether the video parameters really changed before doing + * something expensive. + */ + MPV_EVENT_VIDEO_RECONFIG = 17, + /** + * Similar to MPV_EVENT_VIDEO_RECONFIG. This is relatively uninteresting, + * because there is no such thing as audio output embedding. + */ + MPV_EVENT_AUDIO_RECONFIG = 18, + /** + * Happens when a seek was initiated. Playback stops. Usually it will + * resume with MPV_EVENT_PLAYBACK_RESTART as soon as the seek is finished. + */ + MPV_EVENT_SEEK = 20, + /** + * There was a discontinuity of some sort (like a seek), and playback + * was reinitialized. Usually happens on start of playback and after + * seeking. The main purpose is allowing the client to detect when a seek + * request is finished. + */ + MPV_EVENT_PLAYBACK_RESTART = 21, + /** + * Event sent due to mpv_observe_property(). + * See also mpv_event and mpv_event_property. + */ + MPV_EVENT_PROPERTY_CHANGE = 22, + /** + * Happens if the internal per-mpv_handle ringbuffer overflows, and at + * least 1 event had to be dropped. This can happen if the client doesn't + * read the event queue quickly enough with mpv_wait_event(), or if the + * client makes a very large number of asynchronous calls at once. + * + * Event delivery will continue normally once this event was returned + * (this forces the client to empty the queue completely). + */ + MPV_EVENT_QUEUE_OVERFLOW = 24, + /** + * Triggered if a hook handler was registered with mpv_hook_add(), and the + * hook is invoked. If you receive this, you must handle it, and continue + * the hook with mpv_hook_continue(). + * See also mpv_event and mpv_event_hook. + */ + MPV_EVENT_HOOK = 25, + // Internal note: adjust INTERNAL_EVENT_BASE when adding new events. +} mpv_event_id; + +/** + * Return a string describing the event. For unknown events, NULL is returned. + * + * Note that all events actually returned by the API will also yield a non-NULL + * string with this function. + * + * @param event event ID, see see enum mpv_event_id + * @return A static string giving a short symbolic name of the event. It + * consists of lower-case alphanumeric characters and can include "-" + * characters. This string is suitable for use in e.g. scripting + * interfaces. + * The string is completely static, i.e. doesn't need to be deallocated, + * and is valid forever. + */ +MPV_EXPORT const char *mpv_event_name(mpv_event_id event); + +typedef struct mpv_event_property { + /** + * Name of the property. + */ + const char *name; + /** + * Format of the data field in the same struct. See enum mpv_format. + * This is always the same format as the requested format, except when + * the property could not be retrieved (unavailable, or an error happened), + * in which case the format is MPV_FORMAT_NONE. + */ + mpv_format format; + /** + * Received property value. Depends on the format. This is like the + * pointer argument passed to mpv_get_property(). + * + * For example, for MPV_FORMAT_STRING you get the string with: + * + * char *value = *(char **)(event_property->data); + * + * Note that this is set to NULL if retrieving the property failed (the + * format will be MPV_FORMAT_NONE). + */ + void *data; +} mpv_event_property; + +/** + * Numeric log levels. The lower the number, the more important the message is. + * MPV_LOG_LEVEL_NONE is never used when receiving messages. The string in + * the comment after the value is the name of the log level as used for the + * mpv_request_log_messages() function. + * Unused numeric values are unused, but reserved for future use. + */ +typedef enum mpv_log_level { + MPV_LOG_LEVEL_NONE = 0, /// "no" - disable absolutely all messages + MPV_LOG_LEVEL_FATAL = 10, /// "fatal" - critical/aborting errors + MPV_LOG_LEVEL_ERROR = 20, /// "error" - simple errors + MPV_LOG_LEVEL_WARN = 30, /// "warn" - possible problems + MPV_LOG_LEVEL_INFO = 40, /// "info" - informational message + MPV_LOG_LEVEL_V = 50, /// "v" - noisy informational message + MPV_LOG_LEVEL_DEBUG = 60, /// "debug" - very noisy technical information + MPV_LOG_LEVEL_TRACE = 70, /// "trace" - extremely noisy +} mpv_log_level; + +typedef struct mpv_event_log_message { + /** + * The module prefix, identifies the sender of the message. As a special + * case, if the message buffer overflows, this will be set to the string + * "overflow" (which doesn't appear as prefix otherwise), and the text + * field will contain an informative message. + */ + const char *prefix; + /** + * The log level as string. See mpv_request_log_messages() for possible + * values. The level "no" is never used here. + */ + const char *level; + /** + * The log message. It consists of 1 line of text, and is terminated with + * a newline character. (Before API version 1.6, it could contain multiple + * or partial lines.) + */ + const char *text; + /** + * The same contents as the level field, but as a numeric ID. + * Since API version 1.6. + */ + mpv_log_level log_level; +} mpv_event_log_message; + +/// Since API version 1.9. +typedef enum mpv_end_file_reason { + /** + * The end of file was reached. Sometimes this may also happen on + * incomplete or corrupted files, or if the network connection was + * interrupted when playing a remote file. It also happens if the + * playback range was restricted with --end or --frames or similar. + */ + MPV_END_FILE_REASON_EOF = 0, + /** + * Playback was stopped by an external action (e.g. playlist controls). + */ + MPV_END_FILE_REASON_STOP = 2, + /** + * Playback was stopped by the quit command or player shutdown. + */ + MPV_END_FILE_REASON_QUIT = 3, + /** + * Some kind of error happened that lead to playback abort. Does not + * necessarily happen on incomplete or broken files (in these cases, both + * MPV_END_FILE_REASON_ERROR or MPV_END_FILE_REASON_EOF are possible). + * + * mpv_event_end_file.error will be set. + */ + MPV_END_FILE_REASON_ERROR = 4, + /** + * The file was a playlist or similar. When the playlist is read, its + * entries will be appended to the playlist after the entry of the current + * file, the entry of the current file is removed, and a MPV_EVENT_END_FILE + * event is sent with reason set to MPV_END_FILE_REASON_REDIRECT. Then + * playback continues with the playlist contents. + * Since API version 1.18. + */ + MPV_END_FILE_REASON_REDIRECT = 5, +} mpv_end_file_reason; + +/// Since API version 1.108. +typedef struct mpv_event_start_file { + /** + * Playlist entry ID of the file being loaded now. + */ + int64_t playlist_entry_id; +} mpv_event_start_file; + +typedef struct mpv_event_end_file { + /** + * Corresponds to the values in enum mpv_end_file_reason. + * + * Unknown values should be treated as unknown. + */ + mpv_end_file_reason reason; + /** + * If reason==MPV_END_FILE_REASON_ERROR, this contains a mpv error code + * (one of MPV_ERROR_...) giving an approximate reason why playback + * failed. In other cases, this field is 0 (no error). + * Since API version 1.9. + */ + int error; + /** + * Playlist entry ID of the file that was being played or attempted to be + * played. This has the same value as the playlist_entry_id field in the + * corresponding mpv_event_start_file event. + * Since API version 1.108. + */ + int64_t playlist_entry_id; + /** + * If loading ended, because the playlist entry to be played was for example + * a playlist, and the current playlist entry is replaced with a number of + * other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT + * (other event types may use this for similar but different purposes in the + * future). In this case, playlist_insert_id will be set to the playlist + * entry ID of the first inserted entry, and playlist_insert_num_entries to + * the total number of inserted playlist entries. Note this in this specific + * case, the ID of the last inserted entry is playlist_insert_id+num-1. + * Beware that depending on circumstances, you may observe the new playlist + * entries before seeing the event (e.g. reading the "playlist" property or + * getting a property change notification before receiving the event). + * Since API version 1.108. + */ + int64_t playlist_insert_id; + /** + * See playlist_insert_id. Only non-0 if playlist_insert_id is valid. Never + * negative. + * Since API version 1.108. + */ + int playlist_insert_num_entries; +} mpv_event_end_file; + +typedef struct mpv_event_client_message { + /** + * Arbitrary arguments chosen by the sender of the message. If num_args > 0, + * you can access args[0] through args[num_args - 1] (inclusive). What + * these arguments mean is up to the sender and receiver. + * None of the valid items are NULL. + */ + int num_args; + const char **args; +} mpv_event_client_message; + +typedef struct mpv_event_hook { + /** + * The hook name as passed to mpv_hook_add(). + */ + const char *name; + /** + * Internal ID that must be passed to mpv_hook_continue(). + */ + uint64_t id; +} mpv_event_hook; + +// Since API version 1.102. +typedef struct mpv_event_command { + /** + * Result data of the command. Note that success/failure is signaled + * separately via mpv_event.error. This field is only for result data + * in case of success. Most commands leave it at MPV_FORMAT_NONE. Set + * to MPV_FORMAT_NONE on failure. + */ + mpv_node result; +} mpv_event_command; + +typedef struct mpv_event { + /** + * One of mpv_event. Keep in mind that later ABI compatible releases might + * add new event types. These should be ignored by the API user. + */ + mpv_event_id event_id; + /** + * This is mainly used for events that are replies to (asynchronous) + * requests. It contains a status code, which is >= 0 on success, or < 0 + * on error (a mpv_error value). Usually, this will be set if an + * asynchronous request fails. + * Used for: + * MPV_EVENT_GET_PROPERTY_REPLY + * MPV_EVENT_SET_PROPERTY_REPLY + * MPV_EVENT_COMMAND_REPLY + */ + int error; + /** + * If the event is in reply to a request (made with this API and this + * API handle), this is set to the reply_userdata parameter of the request + * call. Otherwise, this field is 0. + * Used for: + * MPV_EVENT_GET_PROPERTY_REPLY + * MPV_EVENT_SET_PROPERTY_REPLY + * MPV_EVENT_COMMAND_REPLY + * MPV_EVENT_PROPERTY_CHANGE + * MPV_EVENT_HOOK + */ + uint64_t reply_userdata; + /** + * The meaning and contents of the data member depend on the event_id: + * MPV_EVENT_GET_PROPERTY_REPLY: mpv_event_property* + * MPV_EVENT_PROPERTY_CHANGE: mpv_event_property* + * MPV_EVENT_LOG_MESSAGE: mpv_event_log_message* + * MPV_EVENT_CLIENT_MESSAGE: mpv_event_client_message* + * MPV_EVENT_START_FILE: mpv_event_start_file* (since v1.108) + * MPV_EVENT_END_FILE: mpv_event_end_file* + * MPV_EVENT_HOOK: mpv_event_hook* + * MPV_EVENT_COMMAND_REPLY* mpv_event_command* + * other: NULL + * + * Note: future enhancements might add new event structs for existing or new + * event types. + */ + void *data; +} mpv_event; + +/** + * Convert the given src event to a mpv_node, and set *dst to the result. *dst + * is set to a MPV_FORMAT_NODE_MAP, with fields for corresponding mpv_event and + * mpv_event.data/mpv_event_* fields. + * + * The exact details are not completely documented out of laziness. A start + * is located in the "Events" section of the manpage. + * + * *dst may point to newly allocated memory, or pointers in mpv_event. You must + * copy the entire mpv_node if you want to reference it after mpv_event becomes + * invalid (such as making a new mpv_wait_event() call, or destroying the + * mpv_handle from which it was returned). Call mpv_free_node_contents() to free + * any memory allocations made by this API function. + * + * Safe to be called from mpv render API threads. + * + * @param dst Target. This is not read and fully overwritten. Must be released + * with mpv_free_node_contents(). Do not write to pointers returned + * by it. (On error, this may be left as an empty node.) + * @param src The source event. Not modified (it's not const due to the author's + * prejudice of the C version of const). + * @return error code (MPV_ERROR_NOMEM only, if at all) + */ +MPV_EXPORT int mpv_event_to_node(mpv_node *dst, mpv_event *src); + +/** + * Enable or disable the given event. + * + * Some events are enabled by default. Some events can't be disabled. + * + * (Informational note: currently, all events are enabled by default, except + * MPV_EVENT_TICK.) + * + * Safe to be called from mpv render API threads. + * + * @param event See enum mpv_event_id. + * @param enable 1 to enable receiving this event, 0 to disable it. + * @return error code + */ +MPV_EXPORT int mpv_request_event(mpv_handle *ctx, mpv_event_id event, int enable); + +/** + * Enable or disable receiving of log messages. These are the messages the + * command line player prints to the terminal. This call sets the minimum + * required log level for a message to be received with MPV_EVENT_LOG_MESSAGE. + * + * @param min_level Minimal log level as string. Valid log levels: + * no fatal error warn info v debug trace + * The value "no" disables all messages. This is the default. + * An exception is the value "terminal-default", which uses the + * log level as set by the "--msg-level" option. This works + * even if the terminal is disabled. (Since API version 1.19.) + * Also see mpv_log_level. + * @return error code + */ +MPV_EXPORT int mpv_request_log_messages(mpv_handle *ctx, const char *min_level); + +/** + * Wait for the next event, or until the timeout expires, or if another thread + * makes a call to mpv_wakeup(). Passing 0 as timeout will never wait, and + * is suitable for polling. + * + * The internal event queue has a limited size (per client handle). If you + * don't empty the event queue quickly enough with mpv_wait_event(), it will + * overflow and silently discard further events. If this happens, making + * asynchronous requests will fail as well (with MPV_ERROR_EVENT_QUEUE_FULL). + * + * Only one thread is allowed to call this on the same mpv_handle at a time. + * The API won't complain if more than one thread calls this, but it will cause + * race conditions in the client when accessing the shared mpv_event struct. + * Note that most other API functions are not restricted by this, and no API + * function internally calls mpv_wait_event(). Additionally, concurrent calls + * to different mpv_handles are always safe. + * + * As long as the timeout is 0, this is safe to be called from mpv render API + * threads. + * + * @param timeout Timeout in seconds, after which the function returns even if + * no event was received. A MPV_EVENT_NONE is returned on + * timeout. A value of 0 will disable waiting. Negative values + * will wait with an infinite timeout. + * @return A struct containing the event ID and other data. The pointer (and + * fields in the struct) stay valid until the next mpv_wait_event() + * call, or until the mpv_handle is destroyed. You must not write to + * the struct, and all memory referenced by it will be automatically + * released by the API on the next mpv_wait_event() call, or when the + * context is destroyed. The return value is never NULL. + */ +MPV_EXPORT mpv_event *mpv_wait_event(mpv_handle *ctx, double timeout); + +/** + * Interrupt the current mpv_wait_event() call. This will wake up the thread + * currently waiting in mpv_wait_event(). If no thread is waiting, the next + * mpv_wait_event() call will return immediately (this is to avoid lost + * wakeups). + * + * mpv_wait_event() will receive a MPV_EVENT_NONE if it's woken up due to + * this call. But note that this dummy event might be skipped if there are + * already other events queued. All what counts is that the waiting thread + * is woken up at all. + * + * Safe to be called from mpv render API threads. + */ +MPV_EXPORT void mpv_wakeup(mpv_handle *ctx); + +/** + * Set a custom function that should be called when there are new events. Use + * this if blocking in mpv_wait_event() to wait for new events is not feasible. + * + * Keep in mind that the callback will be called from foreign threads. You + * must not make any assumptions of the environment, and you must return as + * soon as possible (i.e. no long blocking waits). Exiting the callback through + * any other means than a normal return is forbidden (no throwing exceptions, + * no longjmp() calls). You must not change any local thread state (such as + * the C floating point environment). + * + * You are not allowed to call any client API functions inside of the callback. + * In particular, you should not do any processing in the callback, but wake up + * another thread that does all the work. The callback is meant strictly for + * notification only, and is called from arbitrary core parts of the player, + * that make no considerations for reentrant API use or allowing the callee to + * spend a lot of time doing other things. Keep in mind that it's also possible + * that the callback is called from a thread while a mpv API function is called + * (i.e. it can be reentrant). + * + * In general, the client API expects you to call mpv_wait_event() to receive + * notifications, and the wakeup callback is merely a helper utility to make + * this easier in certain situations. Note that it's possible that there's + * only one wakeup callback invocation for multiple events. You should call + * mpv_wait_event() with no timeout until MPV_EVENT_NONE is reached, at which + * point the event queue is empty. + * + * If you actually want to do processing in a callback, spawn a thread that + * does nothing but call mpv_wait_event() in a loop and dispatches the result + * to a callback. + * + * Only one wakeup callback can be set. + * + * @param cb function that should be called if a wakeup is required + * @param d arbitrary userdata passed to cb + */ +MPV_EXPORT void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d); + +/** + * Block until all asynchronous requests are done. This affects functions like + * mpv_command_async(), which return immediately and return their result as + * events. + * + * This is a helper, and somewhat equivalent to calling mpv_wait_event() in a + * loop until all known asynchronous requests have sent their reply as event, + * except that the event queue is not emptied. + */ +MPV_EXPORT void mpv_wait_async_requests(mpv_handle *ctx); + +/** + * A hook is like a synchronous event that blocks the player. You register + * a hook handler with this function. You will get an event, which you need + * to handle, and once things are ready, you can let the player continue with + * mpv_hook_continue(). + * + * Currently, hooks can't be removed explicitly. But they will be implicitly + * removed if the mpv_handle it was registered with is destroyed. This also + * continues the hook if it was being handled by the destroyed mpv_handle (but + * this should be avoided, as it might mess up order of hook execution). + * + * Hook handlers are ordered globally by priority and order of registration. + * Handlers for the same hook with same priority are invoked in order of + * registration (the handler registered first is run first). Handlers with + * lower priority are run first (which seems backward). + * + * See the "Hooks" section in the manpage to see which hooks are currently + * defined. + * + * Some hooks might be reentrant (so you get multiple MPV_EVENT_HOOK for the + * same hook). If this can happen for a specific hook type, it will be + * explicitly documented in the manpage. + * + * Only the mpv_handle on which this was called will receive the hook events, + * or can "continue" them. + * + * @param reply_userdata This will be used for the mpv_event.reply_userdata + * field for the received MPV_EVENT_HOOK events. + * If you have no use for this, pass 0. + * @param name The hook name. This should be one of the documented names. But + * if the name is unknown, the hook event will simply be never + * raised. + * @param priority See remarks above. Use 0 as a neutral default. + * @return error code (usually fails only on OOM) + */ +MPV_EXPORT int mpv_hook_add(mpv_handle *ctx, uint64_t reply_userdata, + const char *name, int priority); + +/** + * Respond to a MPV_EVENT_HOOK event. You must call this after you have handled + * the event. There is no way to "cancel" or "stop" the hook. + * + * Calling this will will typically unblock the player for whatever the hook + * is responsible for (e.g. for the "on_load" hook it lets it continue + * playback). + * + * It is explicitly undefined behavior to call this more than once for each + * MPV_EVENT_HOOK, to pass an incorrect ID, or to call this on a mpv_handle + * different from the one that registered the handler and received the event. + * + * @param id This must be the value of the mpv_event_hook.id field for the + * corresponding MPV_EVENT_HOOK. + * @return error code + */ +MPV_EXPORT int mpv_hook_continue(mpv_handle *ctx, uint64_t id); + +#if MPV_ENABLE_DEPRECATED + +/** + * Return a UNIX file descriptor referring to the read end of a pipe. This + * pipe can be used to wake up a poll() based processing loop. The purpose of + * this function is very similar to mpv_set_wakeup_callback(), and provides + * a primitive mechanism to handle coordinating a foreign event loop and the + * libmpv event loop. The pipe is non-blocking. It's closed when the mpv_handle + * is destroyed. This function always returns the same value (on success). + * + * This is in fact implemented using the same underlying code as for + * mpv_set_wakeup_callback() (though they don't conflict), and it is as if each + * callback invocation writes a single 0 byte to the pipe. When the pipe + * becomes readable, the code calling poll() (or select()) on the pipe should + * read all contents of the pipe and then call mpv_wait_event(c, 0) until + * no new events are returned. The pipe contents do not matter and can just + * be discarded. There is not necessarily one byte per readable event in the + * pipe. For example, the pipes are non-blocking, and mpv won't block if the + * pipe is full. Pipes are normally limited to 4096 bytes, so if there are + * more than 4096 events, the number of readable bytes can not equal the number + * of events queued. Also, it's possible that mpv does not write to the pipe + * once it's guaranteed that the client was already signaled. See the example + * below how to do it correctly. + * + * Example: + * + * int pipefd = mpv_get_wakeup_pipe(mpv); + * if (pipefd < 0) + * error(); + * while (1) { + * struct pollfd pfds[1] = { + * { .fd = pipefd, .events = POLLIN }, + * }; + * // Wait until there are possibly new mpv events. + * poll(pfds, 1, -1); + * if (pfds[0].revents & POLLIN) { + * // Empty the pipe. Doing this before calling mpv_wait_event() + * // ensures that no wakeups are missed. It's not so important to + * // make sure the pipe is really empty (it will just cause some + * // additional wakeups in unlikely corner cases). + * char unused[256]; + * read(pipefd, unused, sizeof(unused)); + * while (1) { + * mpv_event *ev = mpv_wait_event(mpv, 0); + * // If MPV_EVENT_NONE is received, the event queue is empty. + * if (ev->event_id == MPV_EVENT_NONE) + * break; + * // Process the event. + * ... + * } + * } + * } + * + * @deprecated this function will be removed in the future. If you need this + * functionality, use mpv_set_wakeup_callback(), create a pipe + * manually, and call write() on your pipe in the callback. + * + * @return A UNIX FD of the read end of the wakeup pipe, or -1 on error. + * On MS Windows/MinGW, this will always return -1. + */ +MPV_EXPORT int mpv_get_wakeup_pipe(mpv_handle *ctx); + +#endif + +/** + * Defining MPV_CPLUGIN_DYNAMIC_SYM during plugin compilation will replace mpv_* + * functions with function pointers. Those pointer will be initialized when + * loading the plugin. + * + * It is recommended to use this symbol table when targeting Windows. The loader + * does not have notion of global symbols. Loading cplugin into mpv process will + * not allow this plugin to call any of the symbols that may be available in + * other modules. Instead cplugin has to link explicitly to specific PE binary, + * libmpv-2.dll/mpv.exe or any other binary that may have linked mpv statically. + * This limits portability of cplugin as it would need to be compiled separately + * for each of target PE binary that includes mpv's symbols. Which in practice + * is unrealistic, as we want one cplugin to be loaded without those restrictions. + * + * Instead of linking to any PE binary, we create function pointers for all mpv's + * exported symbols. For convenience names of entrypoints are redefined to those + * pointer, so no changes are required in cplugin source code, except of defining + * MPV_CPLUGIN_DYNAMIC_SYM. Those function pointer are exported to make them + * available for mpv to init with correct values during runtime, before calling + * `mpv_open_cplugin`. + * + * Note that those pointers are decorated with `selectany` attribute, so no need + * to worry about multiple definitions, linker will keep only single instance. + */ +#ifdef MPV_CPLUGIN_DYNAMIC_SYM + +#define MPV_DEFINE_SYM_PTR(name) \ + MPV_SELECTANY MPV_EXPORT \ + MPV_DECLTYPE(name) *pfn_##name; + +MPV_DEFINE_SYM_PTR(mpv_client_api_version) +#define mpv_client_api_version pfn_mpv_client_api_version +MPV_DEFINE_SYM_PTR(mpv_error_string) +#define mpv_error_string pfn_mpv_error_string +MPV_DEFINE_SYM_PTR(mpv_free) +#define mpv_free pfn_mpv_free +MPV_DEFINE_SYM_PTR(mpv_client_name) +#define mpv_client_name pfn_mpv_client_name +MPV_DEFINE_SYM_PTR(mpv_client_id) +#define mpv_client_id pfn_mpv_client_id +MPV_DEFINE_SYM_PTR(mpv_create) +#define mpv_create pfn_mpv_create +MPV_DEFINE_SYM_PTR(mpv_initialize) +#define mpv_initialize pfn_mpv_initialize +MPV_DEFINE_SYM_PTR(mpv_destroy) +#define mpv_destroy pfn_mpv_destroy +MPV_DEFINE_SYM_PTR(mpv_terminate_destroy) +#define mpv_terminate_destroy pfn_mpv_terminate_destroy +MPV_DEFINE_SYM_PTR(mpv_create_client) +#define mpv_create_client pfn_mpv_create_client +MPV_DEFINE_SYM_PTR(mpv_create_weak_client) +#define mpv_create_weak_client pfn_mpv_create_weak_client +MPV_DEFINE_SYM_PTR(mpv_load_config_file) +#define mpv_load_config_file pfn_mpv_load_config_file +MPV_DEFINE_SYM_PTR(mpv_get_time_ns) +#define mpv_get_time_ns pfn_mpv_get_time_ns +MPV_DEFINE_SYM_PTR(mpv_get_time_us) +#define mpv_get_time_us pfn_mpv_get_time_us +MPV_DEFINE_SYM_PTR(mpv_free_node_contents) +#define mpv_free_node_contents pfn_mpv_free_node_contents +MPV_DEFINE_SYM_PTR(mpv_set_option) +#define mpv_set_option pfn_mpv_set_option +MPV_DEFINE_SYM_PTR(mpv_set_option_string) +#define mpv_set_option_string pfn_mpv_set_option_string +MPV_DEFINE_SYM_PTR(mpv_command) +#define mpv_command pfn_mpv_command +MPV_DEFINE_SYM_PTR(mpv_command_node) +#define mpv_command_node pfn_mpv_command_node +MPV_DEFINE_SYM_PTR(mpv_command_ret) +#define mpv_command_ret pfn_mpv_command_ret +MPV_DEFINE_SYM_PTR(mpv_command_string) +#define mpv_command_string pfn_mpv_command_string +MPV_DEFINE_SYM_PTR(mpv_command_async) +#define mpv_command_async pfn_mpv_command_async +MPV_DEFINE_SYM_PTR(mpv_command_node_async) +#define mpv_command_node_async pfn_mpv_command_node_async +MPV_DEFINE_SYM_PTR(mpv_abort_async_command) +#define mpv_abort_async_command pfn_mpv_abort_async_command +MPV_DEFINE_SYM_PTR(mpv_set_property) +#define mpv_set_property pfn_mpv_set_property +MPV_DEFINE_SYM_PTR(mpv_set_property_string) +#define mpv_set_property_string pfn_mpv_set_property_string +MPV_DEFINE_SYM_PTR(mpv_del_property) +#define mpv_del_property pfn_mpv_del_property +MPV_DEFINE_SYM_PTR(mpv_set_property_async) +#define mpv_set_property_async pfn_mpv_set_property_async +MPV_DEFINE_SYM_PTR(mpv_get_property) +#define mpv_get_property pfn_mpv_get_property +MPV_DEFINE_SYM_PTR(mpv_get_property_string) +#define mpv_get_property_string pfn_mpv_get_property_string +MPV_DEFINE_SYM_PTR(mpv_get_property_osd_string) +#define mpv_get_property_osd_string pfn_mpv_get_property_osd_string +MPV_DEFINE_SYM_PTR(mpv_get_property_async) +#define mpv_get_property_async pfn_mpv_get_property_async +MPV_DEFINE_SYM_PTR(mpv_observe_property) +#define mpv_observe_property pfn_mpv_observe_property +MPV_DEFINE_SYM_PTR(mpv_unobserve_property) +#define mpv_unobserve_property pfn_mpv_unobserve_property +MPV_DEFINE_SYM_PTR(mpv_event_name) +#define mpv_event_name pfn_mpv_event_name +MPV_DEFINE_SYM_PTR(mpv_event_to_node) +#define mpv_event_to_node pfn_mpv_event_to_node +MPV_DEFINE_SYM_PTR(mpv_request_event) +#define mpv_request_event pfn_mpv_request_event +MPV_DEFINE_SYM_PTR(mpv_request_log_messages) +#define mpv_request_log_messages pfn_mpv_request_log_messages +MPV_DEFINE_SYM_PTR(mpv_wait_event) +#define mpv_wait_event pfn_mpv_wait_event +MPV_DEFINE_SYM_PTR(mpv_wakeup) +#define mpv_wakeup pfn_mpv_wakeup +MPV_DEFINE_SYM_PTR(mpv_set_wakeup_callback) +#define mpv_set_wakeup_callback pfn_mpv_set_wakeup_callback +MPV_DEFINE_SYM_PTR(mpv_wait_async_requests) +#define mpv_wait_async_requests pfn_mpv_wait_async_requests +MPV_DEFINE_SYM_PTR(mpv_hook_add) +#define mpv_hook_add pfn_mpv_hook_add +MPV_DEFINE_SYM_PTR(mpv_hook_continue) +#define mpv_hook_continue pfn_mpv_hook_continue +MPV_DEFINE_SYM_PTR(mpv_get_wakeup_pipe) +#define mpv_get_wakeup_pipe pfn_mpv_get_wakeup_pipe + +#endif + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/tools/build.ps1 b/tools/build.ps1 new file mode 100644 index 0000000..64d4bd4 --- /dev/null +++ b/tools/build.ps1 @@ -0,0 +1,46 @@ +param( + [string]$JocCoreSource = "", + [string]$Configuration = "Release", + [string]$BuildDir = (Join-Path $PSScriptRoot "..\build") +) +$ErrorActionPreference = 'Stop' +$root = Resolve-Path (Join-Path $PSScriptRoot "..") + +function Find-CMake { + $command = Get-Command cmake -ErrorAction SilentlyContinue + if ($command) { return $command.Source } + $vswhere = "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" + if (Test-Path $vswhere) { + $install = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath + if ($install) { + $candidate = Join-Path $install "Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe" + if (Test-Path $candidate) { return $candidate } + } + } + throw "cmake not found; install CMake or the Visual Studio C++ tools" +} + +$cmake = Find-CMake +$configure = @("-S", $root, "-B", $BuildDir, "-A", "x64") +if (Get-Command ninja -ErrorAction SilentlyContinue) { + $configure = @("-S", $root, "-B", $BuildDir, "-G", "Ninja") +} else { + $configure += @("-G", "Visual Studio 17 2022") +} +if ($JocCoreSource -ne "") { + $configure += "-DJOC_CORE_SOURCE=$JocCoreSource" +} +& $cmake @configure +if ($LASTEXITCODE -ne 0) { throw "cmake configure failed" } +& $cmake --build $BuildDir --config $Configuration +if ($LASTEXITCODE -ne 0) { throw "cmake build failed" } + +$dll = Join-Path $BuildDir "$Configuration\joc_mpv.dll" +if (-not (Test-Path $dll)) { $dll = Join-Path $BuildDir "joc_mpv.dll" } +Write-Output "" +Write-Output "plugin: $dll" +if (Test-Path (Join-Path (Split-Path $dll) "joc_core.dll")) { + Write-Output "core: $(Join-Path (Split-Path $dll) 'joc_core.dll')" +} else { + Write-Output "core: not next to the plugin; build with -JocCoreSource or copy joc_core.dll there" +} diff --git a/tools/compare_wav.py b/tools/compare_wav.py new file mode 100644 index 0000000..4aaf1b1 --- /dev/null +++ b/tools/compare_wav.py @@ -0,0 +1,39 @@ +import struct, sys, array + +def read_wav(path): + raw = open(path, "rb").read() + assert raw[:4] in (b"RIFF", b"RF64"), raw[:4] + position = 12 + fmt = None + while position + 8 <= len(raw): + chunk = raw[position:position+4] + size = struct.unpack("