kzantow-audio · pull · Apr 15, 2023 · Apr 15, 2023 · Apr 16, 2023 · Apr 16, 2023
diff --git a/.github/workflows/main.yml → .github/workflows/build.yml b/.github/workflows/main.yml → .github/workflows/build.yml
@@ -14,13 +14,14 @@ jobs:
           os: windows-latest
           cc: "cl"
           cxx: "cl"
-          environment_script: "C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Auxiliary/Build/vcvars32.bat"
+          environment_script: "C:/Program Files/Microsoft Visual Studio/2022/Enterprise/VC/Auxiliary/Build/vcvars64.bat"
         - name: "Ubuntu Latest GCC"
           os: ubuntu-latest
-          cc: "gcc-9"
-          cxx: "g++-9"
+          cc: "gcc-10"
+          cxx: "g++-10"
         - name: "macOS Latest Clang"
           os: macos-latest
+          cpp_version: 20
           cc: "clang"
           cxx: "clang++"
     steps:
@@ -101,3 +102,7 @@ jobs:
         if (NOT result EQUAL 0)
           message(FATAL_ERROR "Could not run with ${CMAKE_COMMAND}: Got ${error_message} - ${result}")
         endif()
+
+    - name: Test
+      run: ctest --verbose --test-dir build
+      shell: bash
diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml
@@ -0,0 +1,23 @@
+name: Publish to GitHub Pages with Lunr Search Extension
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+    - name: Install Node.js
+      uses: actions/setup-node@v2
+      with:
+        node-version: '18'
+    - name: Install Antora and the Antora Lunr Extension
+      run: npm i antora @antora/lunr-extension
+    - name: Generate Site
+      run: npx antora docs/antora/antora-playbook.yml
+    - name: Publish to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_branch: www
+        publish_dir: docs/antora/build/site
+
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,15 @@
 .DS_Store
 .idea
 .vscode
+/_site/
 /cmake-build-debug/
 /cmake-build-release/
 /build/
 /x64/
+/.vs
+/docs/antora/build/
+/docs/antora/node_modules/
+/docs/antora/package-lock.json
+/docs/antora/package.json
+/docs/antora_local/
+/python/2023/
diff --git a/.gitmodules b/.gitmodules
@@ -1,9 +0,0 @@
-[submodule "q_io/external/portaudio"]
-	path = q_io/external/portaudio
-	url = https://github.com/PortAudio/portaudio
-[submodule "q_io/external/portmidi"]
-	path = q_io/external/portmidi
-	url = https://github.com/cycfi/portmidi.git
-[submodule "infra"]
-	path = infra
-	url = https://github.com/cycfi/infra.git

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,35 +1,54 @@
 ###############################################################################
-#  Copyright (c) 2016-2021 Joel de Guzman. All rights reserved.
+#  Copyright (c) 2016-2023 Joel de Guzman. All rights reserved.
 #
 #  Distributed under the MIT License (https://opensource.org/licenses/MIT)
 ###############################################################################
-cmake_minimum_required(VERSION 3.5.1)
-
-if(POLICY CMP0990)
-   cmake_policy(SET CMP0077 NEW)
-endif()
+cmake_minimum_required(VERSION 3.16.0)
 
 project(q)
 
-set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
+include(FetchContent)
+
 option(Q_BUILD_EXAMPLES "build Q library examples" ON)
-option(Q_BUILD_TEST "build Q library examples" ON)
+option(Q_BUILD_TEST "build Q library tests" ON)
 option(Q_BUILD_IO "build Q IO library" ON)
 
+###############################################################################
+# Cycfi Infra
+
+FetchContent_Declare(
+  cycfi_infra
+  GIT_REPOSITORY https://github.com/cycfi/infra.git
+  GIT_TAG 2024_MAY
+  GIT_SUBMODULES_RECURSE ON
+)
+
+FetchContent_MakeAvailable(cycfi_infra)
+
+###############################################################################
+# q_lib
+
 add_subdirectory(q_lib)
-add_subdirectory(infra)
+
+###############################################################################
+# q_io
 
 if (Q_BUILD_IO)
    add_subdirectory(q_io)
 endif()
 
+###############################################################################
+# Examples and Tests
+
 if (Q_BUILD_EXAMPLES)
    add_subdirectory(example)
 endif()
 
 if (Q_BUILD_TEST)
    add_subdirectory(test)
+   enable_testing()
 endif()
 
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2021 Joel de Guzman
+Copyright (c) 2014-2024 Joel de Guzman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,75 +1,54 @@
-# ![Q-Logo](docs/assets/images/q-logo-small.png) Audio DSP Library
+# ![Q-Logo](docs/modules/ROOT/images/q-logo-small.png) Audio DSP Library
 
 [![CMake Build Matrix](https://github.com/cycfi/q/workflows/Build/badge.svg)](https://github.com/cycfi/q/actions?query=workflow%3ABuild)
 
 ## Introduction
 
-Q is a cross-platform C++ library for Audio Digital Signal Processing. Aptly
-named after the "Q factor", a dimensionless parameter that describes the
-quality of a resonant circuit, the Q DSP Library is designed to be simple and
-elegant, as the simplicity of its name suggests, and efficient enough to run
-on small microcontrollers.
-
-Q leverages the power of modern C++ and efficient use of functional
-programming techniques, especially function composition using fine-grained
-and reusable function objects (both stateless and stateful), to simplify
-complex DSP programming tasks without sacrificing readability.
-
-Q is the host of some experimental Music related DSP facilities such as
-[Virtual Pickups](http://tinyurl.com/y8cqt8jr) (Virtual pickup placement
-simulator) and [Bitstream Autocorrelation](http://tinyurl.com/yb49zlld) (An
-extremely fast and efficient pitch detection scheme) [the author](#jdeguzman)
-has accumulated over the years as part of research and development, and will
-continue to evolve to accommodate more facilities necessary for the
-fulfillment of various Music related projects.
-
-The library is Open Source and released under the very liberal [MIT
-license](http://tinyurl.com/p6pekvo).
-
-## Announcement
-
-2021 is a year of rethinking. In March, this year, I thought about closing 
-the source code of some of my Open-Source libraries in the first 
-“[Rethinking Open Source][9]” post. Now, I think it is a mistake. At the 
-very least, the pitch-detection code should remain open. And indeed, while 
-I said that the pitch-detection source code will be closed by mid-April, it 
-never happened. It is my gift to the world, and it shall remain open.
-
-Please follow this link for more info: [Keeping it Open: Rethinking Open Source Part 2][10]. 
-
-## News
-
-- 20 Octpber 2021: BACF is not going away: See announcement above. 
-- 14 April 2021: Q v1.0 beta is released: https://github.com/cycfi/q/tree/v1.0_beta
-- 11 March 2021: BACF pitch detection is going away. See announcement above.
-- 4 February 2021: Posted [Fast and Efficient Pitch Detection: Power of Two][7].
-  Bitstream Autocorrelation (BACF) is fast and accurate. What can be better? Well, 
-  two BACFs in parallel!
-- 6 July 2020: Posted [Fast and Efficient Pitch Detection: Revisited][1]. 
-  A long overdue article about the technical details of BACF.
-- 25 June 2020: Pitch/period detection improvements now in master branch.
-- 19 June 2020: Pitch/period detection improvements in develop branch (for
-  now until it becomes stable). Mostly bug fixes; esp. the ability to handle
-  higher frequencies and bigger low-high ranges.
-- 18 May 2020: We're getting closer to a 1.0 release. Busy working on the
-  docs, including small improvements on the example code.
-
-[1]: https://www.cycfi.com/2020/07/fast-and-efficient-pitch-detection-revisited
+Q is a cross-platform C++ library for audio digital signal processing. Q is named after the "Q factor," a dimensionless parameter that describes the quality of a resonant circuit. The Q DSP Library is designed to be simple and elegant, as the simplicity of its name suggests, and efficient enough to run on small microcontrollers.
 
-## Discord
+Q simplifies complex DSP programming tasks without sacrificing readability by leveraging the power of modern C++ and efficient use of functional programming techniques, especially function composition using fine-grained and reusable function objects (both stateless and stateful).
 
-Feel free to join the [discord channel](https://discord.gg/4MymV4EaY5) for 
-discussion and chat with the developer.
+Q is the host of some experimental Music related DSP facilities [the author](#jdeguzman) has accumulated over the years as part of research and development, and will continue to evolve to accommodate more facilities necessary for the fulfillment of various Music related projects.
 
-## Documentation
+The library is Open Source and released under the very liberal [MIT license](http://tinyurl.com/p6pekvo).
+
+> **NOTE:** The library has now reached version 1.0 and has stabilized. The documentation is in sync with the code in the master branch. Any future changes will be developed in feature branches and merged incrementally to the master branch. The develop branch will cease to exist. The API is now stable, and any changes will be documented accordingly.
+>
+> Versions will be in separate branches. The master branch will target the latest version. Currently, it targets v1.5, which will be a significant departure from v1.0, when completed. This update includes the retirement of the BACF (bitstream autocorrelation) based pitch detector and the introduction of a new, much better pitch detection algorithm with integrated onset detection.
+
+**Update:** We're closing in towards v1.5. The Hz pitch detection system is presented in this article series: [Pitch Perfect: Enhanced Pitch Detection Techniques (Part 1)
+](https://www.cycfi.com/2024/09/pitch-perfect-enhanced-pitch-detection-techniques-part-1/)
+
+## Overview
+
+The Q library comprises of two layers:
+
+<p align="center">
+<img src="https://cycfi.github.io/q/q/v1.5-dev/_images/q-layers.svg" width="50%">
+</p>
+
+1. q_io: Audio and MIDI I/O layer. The q_io layer provides cross-platform audio and MIDI host connectivity straight out of the box. The q_io layer is optional. The q_lib layer is usable without it.
+
+2. q_lib: The core DSP library, q_lib is a no-frills, lightweight, header-only library.
+
+### Dependencies
+The dependencies are determined by the arrows.
 
-Documentation is work in progress. Stay tuned...
+* q_io has very minimal dependencies ([portaudio](http://www.portaudio.com/) and
+   [portmidi](http://portmedia.sourceforge.net/portmidi/)) with very loose coupling via thin wrappers that are easy to transplant and port to a host, with or without an operating system, such as an audio plugin or direct to hardware ADC and DAC.
 
-1. [Design and Architecture](https://cycfi.github.io/q/design)
-2. [Setup and Installation](https://cycfi.github.io/q/setup)
-3. [Hello, World](https://cycfi.github.io/q/hello_world)
-4. [Hello, Universe](https://cycfi.github.io/q/hello_universe)
-5. [Fundamentals](https://cycfi.github.io/q/fundamentals)
+* q_io is used in the tests and examples, but can be easily replaced by other mechanisms in an application. DAW (digital audio workstations), for example, have their own audio and MIDI I/O mechanisms.
+
+* q_lib has no dependencies except the standard c++ library.
+
+The *q_io* layer provides cross-platform audio and MIDI host connectivity straight out of the box. The *q_io* layer is optional. The *q_lib* layer is usable without it. *q_io* is used in the tests and examples, but can be easily replaced by other mechanisms in an application.
+
+## Documentation
+
+* [Setup and Installation](https://cycfi.github.io/q/q/v1.5-dev/setup.html)
+* [Quick Start](https://cycfi.github.io/q/q/v1.5-dev/quick_start.html)
+* [Fundamentals](https://cycfi.github.io/q/q/v1.5-dev/fundamentals.html)
+* [Reference](https://cycfi.github.io/q/q/v1.5-dev/index.html)
 
 ## <a name="jdeguzman"></a>About the Author
 
@@ -79,27 +58,28 @@ Since then, he builds his own guitars, effect boxes and synths. He enjoys
 playing distortion-laden rock guitar, composes and produces his own music in
 his home studio.
 
-Joel de Guzman is the principal architect and engineer at [Cycfi Research][1]
-and a consultant at [Ciere Consulting][2]. He is a software engineer
-specializing in advanced C++ and an advocate of Open Source. He has authored
-a number of highly successful Open Source projects such as [Boost.Spirit][3],
-[Boost.Phoenix][4] and [Boost.Fusion][5]. These libraries are all part of the
-[Boost Libraries][6], a well respected, peer-reviewed, Open Source,
-collaborative development effort.
+Joel de Guzman is the principal architect and engineer at [Cycfi
+Research][1]. He is a software engineer specializing in advanced C++ and an
+advocate of Open Source. He has authored a number of highly successful Open
+Source projects such as [Boost.Spirit][3], [Boost.Phoenix][4] and
+[Boost.Fusion][5]. These libraries are all part of the [Boost Libraries][6],
+a well respected, peer-reviewed, Open Source, collaborative development
+effort.
 
 [1]: https://www.cycfi.com/
 [2]: https://ciere.com/
 [3]: http://tinyurl.com/ydhotlaf
 [4]: http://tinyurl.com/y6vkeo5t
 [5]: http://tinyurl.com/ybn5oq9v
 [6]: http://tinyurl.com/jubgged
-[7]: https://bit.ly/3cFkR8E
-[8]: https://www.boost.org/
-[9]: https://www.cycfi.com/2021/03/rethinking-open-source/
-[10]: https://www.cycfi.com/2021/10/keeping-it-open-rethinking-open-source-part-2/
 
----
+## Discord
+
+Feel free to join the [discord channel](https://discord.gg/4MymV4EaY5) for
+discussion and chat with the developer.
 
-*Copyright (c) 2014-2020 Joel de Guzman. All rights reserved.*
+*Copyright (c) 2014-2024 Joel de Guzman. All rights reserved.*
 *Distributed under the [MIT License](https://opensource.org/licenses/MIT)*
 
+
+
diff --git a/docs/.gitattributes b/docs/.gitattributes
@@ -0,0 +1,14 @@
+# See https://help.github.com/en/articles/dealing-with-line-endings
+
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto
+* text eol=lf
+
+# Denote all files that are truly binary and should not be modified.
+*.gif binary
+*.ico binary
+*.jpg binary
+*.mp3 binary
+*.mp4 binary
+*.pdf binary
+*.png binary
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1 +0,0 @@
-/_site/

diff --git a/docs/404.html b/docs/404.html
diff --git a/docs/Gemfile b/docs/Gemfile