From aa6f87532f0ac39c6535d77a1663b39ef0981597 Mon Sep 17 00:00:00 2001 From: shijing xian Date: Mon, 2 Feb 2026 12:58:55 -0800 Subject: [PATCH 1/3] add workflow to generate the docs and upload the docs --- .github/workflows/make-release.yml | 9 +++++ .github/workflows/publish-docs.yml | 55 ++++++++++++++++++++++++++++++ docs/Doxyfile | 12 ++++--- include/livekit/audio_frame.h | 7 ++++ include/livekit/audio_stream.h | 8 ++++- include/livekit/stats.h | 20 +++++++---- 6 files changed, 99 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/publish-docs.yml diff --git a/.github/workflows/make-release.yml b/.github/workflows/make-release.yml index 7d6642d..fc4fbbf 100644 --- a/.github/workflows/make-release.yml +++ b/.github/workflows/make-release.yml @@ -285,3 +285,12 @@ jobs: generate_release_notes: true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # ---------- Publish Docs Job ---------- + publish-docs: + name: Publish Documentation + needs: release + uses: ./.github/workflows/publish-docs.yml + secrets: + DOCS_DEPLOY_AWS_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} + DOCS_DEPLOY_AWS_API_SECRET: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..bc866bf --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,55 @@ +name: Publish docs + +on: + workflow_dispatch: + workflow_call: + secrets: + DOCS_DEPLOY_AWS_ACCESS_KEY: {} + DOCS_DEPLOY_AWS_API_SECRET: {} + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + submodules: true + lfs: true + + # Doxygen is available on ubuntu-latest, but we install explicitly for stability + - name: Install Doxygen + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz + + # Optional: If your Doxyfile uses dot/graphviz for diagrams, graphviz above is useful. + # Optional: If you generate docs via CMake custom target instead of raw doxygen, + # add your build steps here. + + - name: Build Docs (Doxygen) + run: | + doxygen docs/Doxyfile + + - name: S3 Upload + run: | + DOCS_DIR="html" + if [[ ! -d "$DOCS_DIR" ]]; then + echo "Expected docs at $DOCS_DIR but directory not found." + exit 1 + fi + + # Upload to rolling latest (no versioned docs, always overwrite) + aws s3 sync "$DOCS_DIR"/ s3://livekit-docs/cpp --delete + env: + AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} + AWS_DEFAULT_REGION: "us-east-1" + + - name: Expire cloudfront cache + run: | + aws cloudfront create-invalidation --distribution-id EJJ40KLJ3TRY9 --paths "/cpp/*" + env: + AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} + AWS_DEFAULT_REGION: "us-east-1" + diff --git a/docs/Doxyfile b/docs/Doxyfile index 05ef0e9..790e92a 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -27,6 +27,8 @@ # Project related configuration options #--------------------------------------------------------------------------- +PROJECT_NAME = "LiveKit C++ SDK" + # This tag specifies the encoding used for all characters in the configuration # file that follow. The default is UTF-8 which is also the encoding used for all # text before the first occurrence of this tag. Doxygen uses libiconv (or the @@ -1005,7 +1007,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../include/livekit ../docs/index.md ../README.md ../examples/simple_rpc/README.md +INPUT = include/livekit docs/index.md README.md examples/simple_rpc/README.md # This tag can be used to specify the character encoding of the source files # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses @@ -1220,7 +1222,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the Doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = docs/index.md # If the IMPLICIT_DIR_DOCS tag is set to YES, any README.md file found in sub- # directories of the project's root, is used as the documentation for that sub- @@ -1429,8 +1431,8 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = customization/doxygen-awesome.css \ - customization/custom.css +HTML_EXTRA_STYLESHEET = docs/customization/doxygen-awesome.css \ + docs/customization/custom.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -2605,7 +2607,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: NO. -HAVE_DOT = NO +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations Doxygen is allowed # to run in parallel. When set to 0 Doxygen will base this on the number of diff --git a/include/livekit/audio_frame.h b/include/livekit/audio_frame.h index 34d5840..2db2b9b 100644 --- a/include/livekit/audio_frame.h +++ b/include/livekit/audio_frame.h @@ -27,6 +27,13 @@ class AudioFrameBufferInfo; class OwnedAudioFrameBuffer; } // namespace proto +/** + * @brief Represents a raw PCM audio frame with interleaved int16 samples. + * + * AudioFrame holds decoded audio data along with metadata such as sample rate, + * number of channels, and samples per channel. It is used for capturing and + * processing audio in the LiveKit SDK. + */ class AudioFrame { public: /** diff --git a/include/livekit/audio_stream.h b/include/livekit/audio_stream.h index 5baefc9..c066e87 100644 --- a/include/livekit/audio_stream.h +++ b/include/livekit/audio_stream.h @@ -35,8 +35,14 @@ namespace proto { class FfiEvent; } +/** + * @brief Event containing an audio frame received from an AudioStream. + * + * This struct wraps an AudioFrame and is used as the output type when + * reading from an AudioStream. + */ struct AudioFrameEvent { - AudioFrame frame; + AudioFrame frame; ///< The decoded PCM audio frame. }; /** diff --git a/include/livekit/stats.h b/include/livekit/stats.h index 9a0c51c..de56bc0 100644 --- a/include/livekit/stats.h +++ b/include/livekit/stats.h @@ -293,13 +293,21 @@ struct VideoSourceStats { double frames_per_second; }; +/** + * @brief Statistics for audio playout performance. + * + * Contains metrics about audio sample synthesis and playout timing, + * useful for monitoring audio quality and detecting issues like underruns. + */ struct AudioPlayoutStats { - std::string kind; - double synthesized_samples_duration; - std::uint32_t synthesized_samples_events; - double total_samples_duration; - double total_playout_delay; - std::uint64_t total_samples_count; + std::string kind; ///< The type of media ("audio"). + double synthesized_samples_duration; ///< Duration of synthesized samples in + ///< seconds. + std::uint32_t synthesized_samples_events; ///< Number of synthesis events + ///< (e.g., concealment). + double total_samples_duration; ///< Total duration of all samples in seconds. + double total_playout_delay; ///< Cumulative playout delay in seconds. + std::uint64_t total_samples_count; ///< Total number of samples played out. }; struct PeerConnectionStats { From 8c52b93061ff2ba4c7101e767d335a54fc967046 Mon Sep 17 00:00:00 2001 From: shijing xian Date: Mon, 2 Feb 2026 13:24:06 -0800 Subject: [PATCH 2/3] remove the comments --- .github/workflows/publish-docs.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index bc866bf..b83dd63 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -22,10 +22,6 @@ jobs: sudo apt-get update sudo apt-get install -y doxygen graphviz - # Optional: If your Doxyfile uses dot/graphviz for diagrams, graphviz above is useful. - # Optional: If you generate docs via CMake custom target instead of raw doxygen, - # add your build steps here. - - name: Build Docs (Doxygen) run: | doxygen docs/Doxyfile From 5386a5abcdd71830c842871d5fd5f27fdf83d023 Mon Sep 17 00:00:00 2001 From: shijing xian Date: Mon, 2 Feb 2026 14:05:57 -0800 Subject: [PATCH 3/3] fix the aws access variables --- .github/workflows/make-release.yml | 4 +--- .github/workflows/publish-docs.yml | 11 ++++------- 2 files changed, 5 insertions(+), 10 deletions(-) diff --git a/.github/workflows/make-release.yml b/.github/workflows/make-release.yml index fc4fbbf..68ce7dc 100644 --- a/.github/workflows/make-release.yml +++ b/.github/workflows/make-release.yml @@ -291,6 +291,4 @@ jobs: name: Publish Documentation needs: release uses: ./.github/workflows/publish-docs.yml - secrets: - DOCS_DEPLOY_AWS_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} - DOCS_DEPLOY_AWS_API_SECRET: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} + secrets: inherit diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index b83dd63..30e6cb9 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -3,9 +3,6 @@ name: Publish docs on: workflow_dispatch: workflow_call: - secrets: - DOCS_DEPLOY_AWS_ACCESS_KEY: {} - DOCS_DEPLOY_AWS_API_SECRET: {} jobs: docs: @@ -37,15 +34,15 @@ jobs: # Upload to rolling latest (no versioned docs, always overwrite) aws s3 sync "$DOCS_DIR"/ s3://livekit-docs/cpp --delete env: - AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_DEFAULT_REGION: "us-east-1" - name: Expire cloudfront cache run: | aws cloudfront create-invalidation --distribution-id EJJ40KLJ3TRY9 --paths "/cpp/*" env: - AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_DEFAULT_REGION: "us-east-1"