diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index ea45e450..00000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,22 +0,0 @@ -## Contributing to obs-websocket - -### Translating obs-websocket to your language -Localization happens on Crowdin: https://crowdin.com/project/obs-websocket - -### Writing code for obs-websocket -#### Coding Guidelines -- Function and variable names: snake_case for C names, CamelCase for C++ names -- Tabs are 8 columns wide -- 80 columns max. - -#### Commit Guidelines -- Commits follow the 50/72 standard: - - 50 characters max for the title - - One empty line after the title - - Description wrapped to 72 columns max per line. -- Commit titles: - - Use present tense - - Prefix the title with a "scope" name - - e.g: "CI: fix wrong behaviour when packaging for OS X" - - Typical scopes: CI, General, Request, Event, Server - - Look at existing commits for more examples diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..69945f88 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,3 @@ +open_collective: obs-websocket +github: Palakis +custom: https://www.paypal.me/stephanelepin diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 8c118039..215d0d54 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,16 +1,20 @@ ##### Issue type -Bug report? Feature request? Other? + + + + ##### Description -*Replace this with a description of the bug encountered or feature requested.* + ##### Steps to reproduce and other useful info -*If it's a bug, please describe the steps to reproduce it and PLEASE include an OBS log file. Otherwise, remove this section.* + ##### Technical information - **Operating System** : - **OBS Studio version** : +- **obs-websocket version** : ##### Development Environment -*If you're trying to compile obs-websocket, please describe your compiler type and version (e.g: GCC 4.7, VC2013, ...), and the CMake settings used. -Remove this section if it doesn't apply to your case.* + + diff --git a/.github/images/obsws_logo.png b/.github/images/obsws_logo.png new file mode 100644 index 00000000..2bcee839 Binary files /dev/null and b/.github/images/obsws_logo.png differ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..d6fe377d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,35 @@ + + + + +### Description + + +### Motivation and Context + + + + +### How Has This Been Tested? + +Tested OS(s): + +### Types of changes + + + + + + + + + +### Checklist: + + +- [ ] I have read the [**contributing** document](https://github.com/Palakis/obs-websocket/blob/4.x-current/CONTRIBUTING.md). +- [ ] My code is not on the master branch. +- [ ] The code has been tested. +- [ ] All commit messages are properly formatted and commits squashed where appropriate. +- [ ] I have included updates to all appropriate documentation. + diff --git a/.github/workflows/pr_push.yml b/.github/workflows/pr_push.yml new file mode 100644 index 00000000..62836706 --- /dev/null +++ b/.github/workflows/pr_push.yml @@ -0,0 +1,412 @@ +name: 'CI Multiplatform Build' + +on: + push: + paths-ignore: + - 'docs/**' + branches: + - 4.x-current + pull_request: + paths-ignore: + - '**.md' + branches: + - 4.x-current + +jobs: + windows: + name: 'Windows 32+64bit' + runs-on: [windows-latest] + if: contains(github.event.head_commit.message, '[skip ci]') != true + env: + QT_VERSION: '5.10.1' + WINDOWS_DEPS_VERSION: '2017' + CMAKE_GENERATOR: "Visual Studio 16 2019" + CMAKE_SYSTEM_VERSION: "10.0" + steps: + - name: Add msbuild to PATH + uses: microsoft/setup-msbuild@v1.0.0 + - name: 'Checkout' + uses: actions/checkout@v2 + with: + path: ${{ github.workspace }}/obs-websocket + submodules: 'recursive' + - name: 'Checkout OBS' + uses: actions/checkout@v2 + with: + repository: obsproject/obs-studio + path: ${{ github.workspace }}/obs-studio + submodules: 'recursive' + - name: 'Get OBS-Studio git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git fetch --prune --unshallow + echo ::set-env name=OBS_GIT_BRANCH::$(git rev-parse --abbrev-ref HEAD) + echo ::set-env name=OBS_GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=OBS_GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Checkout last OBS-Studio release (${{ env.OBS_GIT_TAG }})' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git checkout ${{ env.OBS_GIT_TAG }} + git submodule update + - name: 'Get obs-websocket git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-websocket + run: | + git fetch --prune --unshallow + echo ::set-env name=GIT_BRANCH::${{ github.event.pull_request.head.ref }} + echo ::set-env name=GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Install prerequisite: QT' + run: | + curl -kLO https://cdn-fastly.obsproject.com/downloads/Qt_${{ env.QT_VERSION }}.7z -f --retry 5 -C - + 7z x Qt_${{ env.QT_VERSION }}.7z -o"${{ github.workspace }}\cmbuild\QT" + - name: 'Install prerequisite: Pre-built OBS dependencies' + run: | + curl -kLO https://cdn-fastly.obsproject.com/downloads/dependencies${{ env.WINDOWS_DEPS_VERSION }}.zip -f --retry 5 -C - + 7z x dependencies${{ env.WINDOWS_DEPS_VERSION }}.zip -o"${{ github.workspace }}\cmbuild\deps" + - name: 'Restore OBS 32-bit build v${{ env.OBS_GIT_TAG }} from cache' + id: build-cache-obs-32 + uses: actions/cache@v1 + env: + CACHE_NAME: 'build-cache-obs-32' + with: + path: ${{ github.workspace }}/obs-studio/build32 + key: ${{ runner.os }}-${{ env.CACHE_NAME }}-${{ env.OBS_GIT_TAG }} + restore-keys: | + ${{ runner.os }}-${{ env.CACHE_NAME }}- + - name: 'Configure OBS 32-bit' + if: steps.build-cache-obs-32.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + mkdir .\build32 + cd .\build32 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A Win32 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017" -DDepsPath="${{ github.workspace }}\cmbuild\deps\win32" -DBUILD_CAPTIONS=YES -DCOPIED_DEPENDENCIES=NO -DCOPY_DEPENDENCIES=YES .. + - name: 'Build OBS-Studio 32-bit' + if: steps.build-cache-obs-32.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + msbuild /m /p:Configuration=RelWithDebInfo .\build32\libobs\libobs.vcxproj + msbuild /m /p:Configuration=RelWithDebInfo .\build32\UI\obs-frontend-api\obs-frontend-api.vcxproj + - name: 'Restore OBS 64-bit build v${{ env.OBS_GIT_TAG }} from cache' + id: build-cache-obs-64 + uses: actions/cache@v1 + env: + CACHE_NAME: 'build-cache-obs-64' + with: + path: ${{ github.workspace }}/obs-studio/build64 + key: ${{ runner.os }}-${{ env.CACHE_NAME }}-${{ env.OBS_GIT_TAG }} + restore-keys: | + ${{ runner.os }}-${{ env.CACHE_NAME }}- + - name: 'Configure OBS 64-bit' + if: steps.build-cache-obs-64.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + mkdir .\build64 + cd .\build64 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A x64 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017_64" -DDepsPath="${{ github.workspace }}\cmbuild\deps\win64" -DBUILD_CAPTIONS=YES -DCOPIED_DEPENDENCIES=NO -DCOPY_DEPENDENCIES=YES .. + - name: 'Build OBS-Studio 64-bit' + if: steps.build-cache-obs-64.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + msbuild /m /p:Configuration=RelWithDebInfo .\build64\libobs\libobs.vcxproj + msbuild /m /p:Configuration=RelWithDebInfo .\build64\UI\obs-frontend-api\obs-frontend-api.vcxproj + - name: 'Configure obs-websocket 64-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + mkdir .\build64 + cd .\build64 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A x64 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017_64" -DLibObs_DIR="${{ github.workspace }}\obs-studio\build64\libobs" -DLIBOBS_INCLUDE_DIR="${{ github.workspace }}\obs-studio\libobs" -DLIBOBS_LIB="${{ github.workspace }}\obs-studio\build64\libobs\RelWithDebInfo\obs.lib" -DOBS_FRONTEND_LIB="${{ github.workspace }}\obs-studio\build64\UI\obs-frontend-api\RelWithDebInfo\obs-frontend-api.lib" .. + - name: 'Configure obs-websocket 32-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + mkdir .\build32 + cd .\build32 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A Win32 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017" -DLibObs_DIR="${{ github.workspace }}\obs-studio\build32\libobs" -DLIBOBS_INCLUDE_DIR="${{ github.workspace }}\obs-studio\libobs" -DLIBOBS_LIB="${{ github.workspace }}\obs-studio\build32\libobs\RelWithDebInfo\obs.lib" -DOBS_FRONTEND_LIB="${{ github.workspace }}\obs-studio\build32\UI\obs-frontend-api\RelWithDebInfo\obs-frontend-api.lib" .. + - name: 'Build obs-websocket 64-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: msbuild /m /p:Configuration=RelWithDebInfo .\build64\obs-websocket.sln + - name: 'Build obs-websocket 32-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: msbuild /m /p:Configuration=RelWithDebInfo .\build32\obs-websocket.sln + - name: 'Set PR artifact filename' + shell: bash + run: | + FILENAME="obs-websocket-${{ env.GIT_HASH }}-Windows" + echo "::set-env name=FILENAME::$FILENAME" + - name: 'Package obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + mkdir package + cd package + 7z a "${{ env.WIN_FILENAME }}.zip" "..\release\*" + iscc ..\installer\installer.iss /O. /F"${{ env.WIN_FILENAME }}-Installer" + - name: 'Publish ${{ env.WIN_FILENAME }}.zip' + if: success() + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_HASH }}-Windows' + path: ${{ github.workspace }}/obs-websocket/package/*.zip + - name: 'Publish ${{ env.WIN_FILENAME }}-Installer.exe' + if: success() + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_HASH }}-Windows-Installer' + path: ${{ github.workspace }}/obs-websocket/package/*.exe + ubuntu64: + name: "Linux/Ubuntu 64-bit" + runs-on: [ubuntu-latest] + if: contains(github.event.head_commit.message, '[skip ci]') != true + steps: + - name: 'Checkout' + uses: actions/checkout@v2 + with: + path: ${{ github.workspace }}/obs-websocket + submodules: 'recursive' + - name: 'Checkout OBS' + uses: actions/checkout@v2 + with: + repository: obsproject/obs-studio + path: ${{ github.workspace }}/obs-studio + submodules: 'recursive' + - name: 'Get OBS-Studio git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git fetch --prune --unshallow + echo ::set-env name=OBS_GIT_BRANCH::$(git rev-parse --abbrev-ref HEAD) + echo ::set-env name=OBS_GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=OBS_GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Checkout last OBS-Studio release (${{ env.OBS_GIT_TAG }})' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git checkout ${{ env.OBS_GIT_TAG }} + git submodule update + - name: 'Get obs-websocket git info' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + git fetch --prune --unshallow + echo ::set-env name=GIT_BRANCH::${{ github.event.pull_request.head.ref }} + echo ::set-env name=GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Install prerequisites (Apt)' + shell: bash + run: | + sudo dpkg --add-architecture amd64 + sudo apt-get -qq update + sudo apt-get install -y \ + build-essential \ + checkinstall \ + cmake \ + libasound2-dev \ + libavcodec-dev \ + libavdevice-dev \ + libavfilter-dev \ + libavformat-dev \ + libavutil-dev \ + libcurl4-openssl-dev \ + libfdk-aac-dev \ + libfontconfig-dev \ + libfreetype6-dev \ + libgl1-mesa-dev \ + libjack-jackd2-dev \ + libjansson-dev \ + libluajit-5.1-dev \ + libpulse-dev \ + libqt5x11extras5-dev \ + libspeexdsp-dev \ + libswresample-dev \ + libswscale-dev \ + libudev-dev \ + libv4l-dev \ + libva-dev \ + libvlc-dev \ + libx11-dev \ + libx264-dev \ + libxcb-randr0-dev \ + libxcb-shm0-dev \ + libxcb-xinerama0-dev \ + libxcomposite-dev \ + libxinerama-dev \ + libmbedtls-dev \ + pkg-config \ + python3-dev \ + qtbase5-dev \ + libqt5svg5-dev \ + swig + - name: 'Configure OBS-Studio' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + mkdir ./build + cd ./build + cmake -DBUILD_CAPTIONS=YES -DDISABLE_PLUGINS=YES -DENABLE_SCRIPTING=NO -DUNIX_STRUCTURE=YES -DCMAKE_INSTALL_PREFIX=/usr .. + - name: 'Build OBS-Studio' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + set -e + cd ./build + make -j4 libobs obs-frontend-api + - name: 'Install OBS-Studio' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + cd ./build + sudo cp ./libobs/libobs.so /usr/lib + sudo cp ./UI/obs-frontend-api/libobs-frontend-api.so /usr/lib + sudo mkdir -p /usr/include/obs + sudo cp ../UI/obs-frontend-api/obs-frontend-api.h /usr/include/obs/obs-frontend-api.h + - name: 'Configure obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + mkdir ./build + cd ./build + cmake -DLIBOBS_INCLUDE_DIR=${{ github.workspace }}/obs-studio/libobs -DCMAKE_INSTALL_PREFIX=/usr .. + - name: 'Build obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + set -e + cd ./build + make -j4 + - name: 'Set PR artifact filename' + shell: bash + run: | + FILENAME="obs-websocket-1-${{ env.GIT_HASH }}-1_amd64.deb" + echo "::set-env name=FILENAME::$FILENAME" + - name: 'Package ${{ env.FILENAME }}' + if: success() + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + VERSION="1-${{ env.GIT_HASH }}-git" + cd ./build + sudo checkinstall -y --type=debian --fstrans=no -nodoc \ + --backup=no --deldoc=yes --install=no --pkgname=obs-websocket --pkgversion=$VERSION \ + --pkglicense="GPLv2.0" --maintainer="${{ github.event.pusher.email }}" --pkggroup="video" \ + --pkgsource="${{ github.event.repository.html_url }}" \ + --requires="obs-studio,libqt5core5a,libqt5widgets5,qt5-image-formats-plugins" \ + --pakdir="../package" + sudo chmod ao+r ../package/* + cd - + - name: 'Publish ${{ env.FILENAME }}' + if: success() + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_HASH }}-linux' + path: '${{ github.workspace }}/obs-websocket/package/*.deb' + macos64: + name: "macOS 64-bit" + runs-on: [macos-latest] + if: contains(github.event.head_commit.message, '[skip ci]') != true + env: + MACOS_DEPS_VERSION: '2020-04-18' + QT_VERSION: '5.14.1' + steps: + - name: 'Checkout' + uses: actions/checkout@v2 + with: + path: ${{ github.workspace }}/obs-websocket + submodules: 'recursive' + - name: 'Checkout OBS' + uses: actions/checkout@v2 + with: + repository: obsproject/obs-studio + path: ${{ github.workspace }}/obs-studio + submodules: 'recursive' + - name: 'Get OBS-Studio git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git fetch --prune --unshallow + echo ::set-env name=OBS_GIT_BRANCH::$(git rev-parse --abbrev-ref HEAD) + echo ::set-env name=OBS_GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=OBS_GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Checkout last OBS-Studio release (${{ env.OBS_GIT_TAG }})' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git checkout ${{ env.OBS_GIT_TAG }} + git submodule update + - name: 'Get obs-websocket git info' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + git fetch --prune --unshallow + echo ::set-env name=GIT_BRANCH::${{ github.event.pull_request.head.ref }} + echo ::set-env name=GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Install prerequisites (Homebrew)' + shell: bash + run: | + brew bundle --file ${{ github.workspace }}/obs-websocket/CI/macos/Brewfile + - name: 'Install prerequisite: Pre-built OBS dependencies' + shell: bash + run: | + curl -L -O https://github.com/obsproject/obs-deps/releases/download/${{ env.MACOS_DEPS_VERSION }}/osx-deps-${{ env.MACOS_DEPS_VERSION }}.tar.gz + tar -xf ${{ github.workspace }}/osx-deps-${{ env.MACOS_DEPS_VERSION }}.tar.gz -C "/tmp" + - name: 'Configure OBS Studio' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + mkdir build + cd build + cmake -DBUILD_CAPTIONS=YES -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11 -DENABLE_SCRIPTING=NO -DDepsPath=/tmp/obsdeps -DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt/${{ env.QT_VERSION }}/lib/cmake .. + - name: 'Build OBS Studio libraries' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + set -e + cd ./build + make -j4 libobs obs-frontend-api + - name: 'Configure obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + mkdir build + cd build + cmake -DQTDIR=/usr/local/Cellar/qt/${{ env.QT_VERSION }} -DLIBOBS_INCLUDE_DIR=${{ github.workspace }}/obs-studio/libobs -DLIBOBS_LIB=${{ github.workspace }}/obs-studio/libobs -DOBS_FRONTEND_LIB="${{ github.workspace }}/obs-studio/build/UI/obs-frontend-api/libobs-frontend-api.dylib" -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/usr .. + - name: 'Build obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + set -e + cd ./build + make -j4 + - name: 'Install prerequisite: Packages app' + if: success() + shell: bash + run: | + curl -L -O https://s3-us-west-2.amazonaws.com/obs-nightly/Packages.pkg + sudo installer -pkg ${{ github.workspace }}/Packages.pkg -target / + - name: 'Set PR artifact filename' + shell: bash + run: | + FILENAME_UNSIGNED="obs-websocket-${{ env.GIT_HASH }}-macOS-Unsigned.pkg" + echo "::set-env name=FILENAME_UNSIGNED::$FILENAME_UNSIGNED" + - name: 'Fix linked dynamic library paths' + if: success() + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + install_name_tool -change /usr/local/opt/qt/lib/QtWidgets.framework/Versions/5/QtWidgets @executable_path/../Frameworks/QtWidgets.framework/Versions/5/QtWidgets ./build/obs-websocket.so + install_name_tool -change /usr/local/opt/qt/lib/QtGui.framework/Versions/5/QtGui @executable_path/../Frameworks/QtGui.framework/Versions/5/QtGui ./build/obs-websocket.so + install_name_tool -change /usr/local/opt/qt/lib/QtCore.framework/Versions/5/QtCore @executable_path/../Frameworks/QtCore.framework/Versions/5/QtCore ./build/obs-websocket.so + echo "Dependencies for obs-websocket" + otool -L ./build/obs-websocket.so + - name: 'Package ${{ env.FILENAME }}' + if: success() + working-directory: ./obs-websocket + shell: bash + run: | + packagesbuild ./CI/macos/obs-websocket.pkgproj + mv ./release/obs-websocket.pkg ./release/${{ env.FILENAME_UNSIGNED }} + - name: 'Publish ${{ env.FILENAME_UNSIGNED }} artifact' + if: success() + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_HASH }}-macOS' + path: ${{ github.workspace }}/obs-websocket/release/*.pkg diff --git a/.github/workflows/tag_release.yml b/.github/workflows/tag_release.yml new file mode 100644 index 00000000..698ce49a --- /dev/null +++ b/.github/workflows/tag_release.yml @@ -0,0 +1,484 @@ +name: 'CI Multiplatform Release' + +on: + push: + paths-ignore: + - 'docs/**' + tags: + - '[45].[0-9]+.[0-9]+' + +jobs: + windows: + name: 'Windows 32+64bit' + runs-on: [windows-latest] + env: + QT_VERSION: '5.10.1' + WINDOWS_DEPS_VERSION: '2017' + CMAKE_GENERATOR: "Visual Studio 16 2019" + CMAKE_SYSTEM_VERSION: "10.0" + steps: + - name: 'Add msbuild to PATH' + uses: microsoft/setup-msbuild@v1.0.0 + - name: 'Checkout' + uses: actions/checkout@v2 + with: + path: ${{ github.workspace }}/obs-websocket + submodules: 'recursive' + - name: 'Checkout OBS' + uses: actions/checkout@v2 + with: + repository: obsproject/obs-studio + path: ${{ github.workspace }}/obs-studio + submodules: 'recursive' + - name: 'Get OBS-Studio git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git fetch --prune --unshallow + echo ::set-env name=OBS_GIT_BRANCH::$(git rev-parse --abbrev-ref HEAD) + echo ::set-env name=OBS_GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=OBS_GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Checkout last OBS-Studio release (${{ env.OBS_GIT_TAG }})' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git checkout ${{ env.OBS_GIT_TAG }} + git submodule update + - name: 'Get obs-websocket git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-websocket + run: | + git fetch --prune --unshallow + echo ::set-env name=GIT_BRANCH::${{ github.event.pull_request.head.ref }} + echo ::set-env name=GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Install prerequisite: QT' + run: | + curl -kLO https://cdn-fastly.obsproject.com/downloads/Qt_${{ env.QT_VERSION }}.7z -f --retry 5 -C - + 7z x Qt_${{ env.QT_VERSION }}.7z -o"${{ github.workspace }}\cmbuild\QT" + - name: 'Install prerequisite: Pre-built OBS dependencies' + run: | + curl -kLO https://cdn-fastly.obsproject.com/downloads/dependencies${{ env.WINDOWS_DEPS_VERSION }}.zip -f --retry 5 -C - + 7z x dependencies${{ env.WINDOWS_DEPS_VERSION }}.zip -o"${{ github.workspace }}\cmbuild\deps" + - name: 'Restore OBS 32-bit build v${{ env.OBS_GIT_TAG }} from cache' + id: build-cache-obs-32 + uses: actions/cache@v1 + env: + CACHE_NAME: 'build-cache-obs-32' + with: + path: ${{ github.workspace }}/obs-studio/build32 + key: ${{ runner.os }}-${{ env.CACHE_NAME }}-${{ env.OBS_GIT_TAG }} + restore-keys: | + ${{ runner.os }}-${{ env.CACHE_NAME }}- + - name: 'Configure OBS 32-bit' + if: steps.build-cache-obs-32.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + mkdir .\build32 + cd .\build32 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A Win32 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017" -DDepsPath="${{ github.workspace }}\cmbuild\deps\win32" -DBUILD_CAPTIONS=YES -DCOPIED_DEPENDENCIES=NO -DCOPY_DEPENDENCIES=YES .. + - name: 'Build OBS-Studio 32-bit' + if: steps.build-cache-obs-32.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + msbuild /m /p:Configuration=RelWithDebInfo .\build32\libobs\libobs.vcxproj + msbuild /m /p:Configuration=RelWithDebInfo .\build32\UI\obs-frontend-api\obs-frontend-api.vcxproj + - name: 'Restore OBS 64-bit build v${{ env.OBS_GIT_TAG }} from cache' + id: build-cache-obs-64 + uses: actions/cache@v1 + env: + CACHE_NAME: 'build-cache-obs-64' + with: + path: ${{ github.workspace }}/obs-studio/build64 + key: ${{ runner.os }}-${{ env.CACHE_NAME }}-${{ env.OBS_GIT_TAG }} + restore-keys: | + ${{ runner.os }}-${{ env.CACHE_NAME }}- + - name: 'Configure OBS 64-bit' + if: steps.build-cache-obs-64.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + mkdir .\build64 + cd .\build64 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A x64 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017_64" -DDepsPath="${{ github.workspace }}\cmbuild\deps\win64" -DBUILD_CAPTIONS=YES -DCOPIED_DEPENDENCIES=NO -DCOPY_DEPENDENCIES=YES .. + - name: 'Build OBS-Studio 64-bit' + if: steps.build-cache-obs-64.outputs.cache-hit != 'true' + working-directory: ${{ github.workspace }}/obs-studio + run: | + msbuild /m /p:Configuration=RelWithDebInfo .\build64\libobs\libobs.vcxproj + msbuild /m /p:Configuration=RelWithDebInfo .\build64\UI\obs-frontend-api\obs-frontend-api.vcxproj + - name: 'Configure obs-websocket 64-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + mkdir .\build64 + cd .\build64 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A x64 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017_64" -DLibObs_DIR="${{ github.workspace }}\obs-studio\build64\libobs" -DLIBOBS_INCLUDE_DIR="${{ github.workspace }}\obs-studio\libobs" -DLIBOBS_LIB="${{ github.workspace }}\obs-studio\build64\libobs\RelWithDebInfo\obs.lib" -DOBS_FRONTEND_LIB="${{ github.workspace }}\obs-studio\build64\UI\obs-frontend-api\RelWithDebInfo\obs-frontend-api.lib" .. + - name: 'Configure obs-websocket 32-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + mkdir .\build32 + cd .\build32 + cmake -G "${{ env.CMAKE_GENERATOR }}" -A Win32 -DCMAKE_SYSTEM_VERSION="${{ env.CMAKE_SYSTEM_VERSION }}" -DQTDIR="${{ github.workspace }}\cmbuild\QT\${{ env.QT_VERSION }}\msvc2017" -DLibObs_DIR="${{ github.workspace }}\obs-studio\build32\libobs" -DLIBOBS_INCLUDE_DIR="${{ github.workspace }}\obs-studio\libobs" -DLIBOBS_LIB="${{ github.workspace }}\obs-studio\build32\libobs\RelWithDebInfo\obs.lib" -DOBS_FRONTEND_LIB="${{ github.workspace }}\obs-studio\build32\UI\obs-frontend-api\RelWithDebInfo\obs-frontend-api.lib" .. + - name: 'Build obs-websocket 64-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: msbuild /m /p:Configuration=RelWithDebInfo .\build64\obs-websocket.sln + - name: 'Build obs-websocket 32-bit' + working-directory: ${{ github.workspace }}/obs-websocket + run: msbuild /m /p:Configuration=RelWithDebInfo .\build32\obs-websocket.sln + - name: 'Set release filename' + shell: bash + run: | + FILENAME="obs-websocket-${{ env.GIT_TAG }}-Windows" + echo "::set-env name=WIN_FILENAME::$FILENAME" + - name: 'Package obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + mkdir package + cd package + 7z a "${{ env.WIN_FILENAME }}.zip" "..\release\*" + iscc ..\installer\installer.iss /O. /F"${{ env.WIN_FILENAME }}-Installer" + - name: 'Publish ${{ env.WIN_FILENAME }}.zip' + if: success() + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_TAG }}-Windows' + path: ${{ github.workspace }}/obs-websocket/package/*.zip + - name: 'Publish ${{ env.WIN_FILENAME }}-Installer.exe' + if: success() + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_TAG }}-Windows-Installer' + path: ${{ github.workspace }}/obs-websocket/package/*.exe + ubuntu64: + name: "Linux/Ubuntu 64-bit" + runs-on: [ubuntu-latest] + steps: + - name: 'Checkout' + uses: actions/checkout@v2 + with: + path: ${{ github.workspace }}/obs-websocket + submodules: 'recursive' + - name: 'Checkout OBS' + uses: actions/checkout@v2 + with: + repository: obsproject/obs-studio + path: ${{ github.workspace }}/obs-studio + submodules: 'recursive' + - name: 'Get OBS-Studio git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git fetch --prune --unshallow + echo ::set-env name=OBS_GIT_BRANCH::$(git rev-parse --abbrev-ref HEAD) + echo ::set-env name=OBS_GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=OBS_GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Checkout last OBS-Studio release (${{ env.OBS_GIT_TAG }})' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git checkout ${{ env.OBS_GIT_TAG }} + git submodule update + - name: 'Get obs-websocket git info' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + git fetch --prune --unshallow + echo ::set-env name=GIT_BRANCH::${{ github.event.pull_request.head.ref }} + echo ::set-env name=GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Install prerequisites (Apt)' + shell: bash + run: | + sudo dpkg --add-architecture amd64 + sudo apt-get -qq update + sudo apt-get install -y \ + build-essential \ + checkinstall \ + cmake \ + libasound2-dev \ + libavcodec-dev \ + libavdevice-dev \ + libavfilter-dev \ + libavformat-dev \ + libavutil-dev \ + libcurl4-openssl-dev \ + libfdk-aac-dev \ + libfontconfig-dev \ + libfreetype6-dev \ + libgl1-mesa-dev \ + libjack-jackd2-dev \ + libjansson-dev \ + libluajit-5.1-dev \ + libpulse-dev \ + libqt5x11extras5-dev \ + libspeexdsp-dev \ + libswresample-dev \ + libswscale-dev \ + libudev-dev \ + libv4l-dev \ + libva-dev \ + libvlc-dev \ + libx11-dev \ + libx264-dev \ + libxcb-randr0-dev \ + libxcb-shm0-dev \ + libxcb-xinerama0-dev \ + libxcomposite-dev \ + libxinerama-dev \ + libmbedtls-dev \ + pkg-config \ + python3-dev \ + qtbase5-dev \ + libqt5svg5-dev \ + swig + - name: 'Configure OBS-Studio' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + mkdir ./build + cd ./build + cmake -DBUILD_CAPTIONS=YES -DDISABLE_PLUGINS=YES -DENABLE_SCRIPTING=NO -DUNIX_STRUCTURE=YES -DCMAKE_INSTALL_PREFIX=/usr .. + - name: 'Build OBS-Studio' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + set -e + cd ./build + make -j4 libobs obs-frontend-api + - name: 'Install OBS-Studio' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + cd ./build + sudo cp ./libobs/libobs.so /usr/lib + sudo cp ./UI/obs-frontend-api/libobs-frontend-api.so /usr/lib + sudo mkdir -p /usr/include/obs + sudo cp ../UI/obs-frontend-api/obs-frontend-api.h /usr/include/obs/obs-frontend-api.h + - name: 'Configure obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + mkdir ./build + cd ./build + cmake -DLIBOBS_INCLUDE_DIR=${{ github.workspace }}/obs-studio/libobs -DCMAKE_INSTALL_PREFIX=/usr .. + - name: 'Build obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + set -e + cd ./build + make -j4 + - name: 'Set release filename' + shell: bash + run: | + FILENAME="obs-websocket-${{ env.GIT_TAG }}-1_amd64.deb" + echo "::set-env name=LINUX_FILENAME::$FILENAME" + - name: 'Package ${{ env.LINUX_FILENAME }}' + if: success() + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + VERSION="${{ env.GIT_TAG }}" + cd ./build + sudo checkinstall -y --type=debian --fstrans=no -nodoc \ + --backup=no --deldoc=yes --install=no --pkgname=obs-websocket --pkgversion=$VERSION \ + --pkglicense="GPLv2.0" --maintainer="${{ github.event.pusher.email }}" --pkggroup="video" \ + --pkgsource="${{ github.event.repository.html_url }}" \ + --requires="obs-studio,libqt5core5a,libqt5widgets5,qt5-image-formats-plugins" \ + --pakdir="../package" + sudo chmod ao+r ../package/* + cd - + - name: 'Publish ${{ env.LINUX_FILENAME }}' + if: success() + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_TAG }}-linux' + path: '${{ github.workspace }}/obs-websocket/package/*.deb' + macos64: + name: "macOS 64-bit" + runs-on: [macos-latest] + env: + MACOS_DEPS_VERSION: '2020-04-18' + QT_VERSION: '5.14.1' + steps: + - name: 'Checkout' + uses: actions/checkout@v2 + with: + path: ${{ github.workspace }}/obs-websocket + submodules: 'recursive' + - name: 'Checkout OBS' + uses: actions/checkout@v2 + with: + repository: obsproject/obs-studio + path: ${{ github.workspace }}/obs-studio + submodules: 'recursive' + - name: 'Get OBS-Studio git info' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git fetch --prune --unshallow + echo ::set-env name=OBS_GIT_BRANCH::$(git rev-parse --abbrev-ref HEAD) + echo ::set-env name=OBS_GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=OBS_GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Checkout last OBS-Studio release (${{ env.OBS_GIT_TAG }})' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + git checkout ${{ env.OBS_GIT_TAG }} + git submodule update + - name: 'Get obs-websocket git info' + working-directory: ${{ github.workspace }}/obs-websocket + run: | + git fetch --prune --unshallow + echo ::set-env name=GIT_BRANCH::${{ github.event.pull_request.head.ref }} + echo ::set-env name=GIT_HASH::$(git rev-parse --short HEAD) + echo ::set-env name=GIT_TAG::$(git describe --tags --abbrev=0) + - name: 'Install prerequisites (Homebrew)' + shell: bash + run: | + brew bundle --file ${{ github.workspace }}/obs-websocket/CI/macos/Brewfile + - name: 'Install prerequisite: Pre-built OBS dependencies' + shell: bash + run: | + curl -L -O https://github.com/obsproject/obs-deps/releases/download/${{ env.MACOS_DEPS_VERSION }}/osx-deps-${{ env.MACOS_DEPS_VERSION }}.tar.gz + tar -xf ${{ github.workspace }}/osx-deps-${{ env.MACOS_DEPS_VERSION }}.tar.gz -C "/tmp" + - name: 'Configure OBS Studio' + shell: bash + working-directory: ${{ github.workspace }}/obs-studio + run: | + mkdir build + cd build + cmake -DBUILD_CAPTIONS=YES -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11 -DENABLE_SCRIPTING=NO -DDepsPath=/tmp/obsdeps -DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt/${{ env.QT_VERSION }}/lib/cmake .. + - name: 'Build OBS Studio libraries' + working-directory: ${{ github.workspace }}/obs-studio + shell: bash + run: | + set -e + cd ./build + make -j4 libobs obs-frontend-api + - name: 'Configure obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + mkdir build + cd build + cmake -DQTDIR=/usr/local/Cellar/qt/${{ env.QT_VERSION }} -DLIBOBS_INCLUDE_DIR=${{ github.workspace }}/obs-studio/libobs -DLIBOBS_LIB=${{ github.workspace }}/obs-studio/libobs -DOBS_FRONTEND_LIB="${{ github.workspace }}/obs-studio/build/UI/obs-frontend-api/libobs-frontend-api.dylib" -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/usr .. + - name: 'Build obs-websocket' + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + set -e + cd ./build + make -j4 + - name: 'Install prerequisite: Packages app' + if: success() + shell: bash + run: | + curl -L -O https://s3-us-west-2.amazonaws.com/obs-nightly/Packages.pkg + sudo installer -pkg ${{ github.workspace }}/Packages.pkg -target / + - name: 'Set release filename' + if: success() && startsWith(github.ref, 'refs/tags') + shell: bash + run: | + FILENAME_UNSIGNED="obs-websocket-${{ env.GIT_TAG }}-macOS-Unsigned.pkg" + FILENAME="obs-websocket-${{ env.GIT_TAG }}-macOS.pkg" + echo "::set-env name=MAC_FILENAME_UNSIGNED::$FILENAME_UNSIGNED" + echo "::set-env name=MAC_FILENAME::$FILENAME" + - name: 'Fix linked dynamic library paths' + if: success() + working-directory: ${{ github.workspace }}/obs-websocket + shell: bash + run: | + install_name_tool -change /usr/local/opt/qt/lib/QtWidgets.framework/Versions/5/QtWidgets @executable_path/../Frameworks/QtWidgets.framework/Versions/5/QtWidgets ./build/obs-websocket.so + install_name_tool -change /usr/local/opt/qt/lib/QtGui.framework/Versions/5/QtGui @executable_path/../Frameworks/QtGui.framework/Versions/5/QtGui ./build/obs-websocket.so + install_name_tool -change /usr/local/opt/qt/lib/QtCore.framework/Versions/5/QtCore @executable_path/../Frameworks/QtCore.framework/Versions/5/QtCore ./build/obs-websocket.so + echo "Dependencies for obs-websocket" + otool -L ./build/obs-websocket.so + - name: 'Install Apple Developer Certificate' + if: success() + uses: apple-actions/import-codesign-certs@253ddeeac23f2bdad1646faac5c8c2832e800071 + with: + p12-file-base64: ${{ secrets.MACOS_CERT_CODESIGN }} + p12-password: ${{ secrets.MACOS_CERT_PASS }} + - name: 'Code signing' + if: success() + working-directory: ./obs-websocket + shell: bash + run: | + set -e + codesign --sign "${{ secrets.MACOS_IDENT_CODESIGN }}" ./build/obs-websocket.so + packagesbuild ./CI/macos/obs-websocket.pkgproj + mv ./release/obs-websocket.pkg ./release/${{ env.MAC_FILENAME_UNSIGNED }} + productsign --sign "${{ secrets.MACOS_IDENT_INSTALLER }}" ./release/${{ env.MAC_FILENAME_UNSIGNED }} ./release/${{ env.MAC_FILENAME }} + rm ./release/${{ env.MAC_FILENAME_UNSIGNED }} + - name: 'Notarization' + if: success() + working-directory: ./obs-websocket + shell: bash + run: | + set -e + xcrun altool --store-password-in-keychain-item "AC_PASSWORD" -u "${{ secrets.MACOS_IDENT_USER }}" -p "${{ secrets.MACOS_IDENT_PASS }}" + xcnotary precheck ./release/${{ env.MAC_FILENAME }} + if [ "$?" -eq 0 ]; then xcnotary notarize ./release/${{ env.MAC_FILENAME }} --developer-account "${{ secrets.MACOS_IDENT_USER }}" --developer-password-keychain-item "AC_PASSWORD" --provider "${{ secrets.MACOS_IDENT_PROVIDER }}"; fi + - name: 'Publish ${{ env.MAC_FILENAME }} artifact' + if: success() && startsWith(github.ref, 'refs/tags') + uses: actions/upload-artifact@v2-preview + with: + name: '${{ env.GIT_TAG }}-macOS' + path: ${{ github.workspace }}/obs-websocket/release/*.pkg + make-release: + name: 'Create and upload release' + runs-on: [ubuntu-latest] + needs: [windows, ubuntu64, macos64] + steps: + - name: 'Get the version' + shell: bash + id: get_version + run: | + echo ::set-env name=TAG_VERSION::${GITHUB_REF/refs\/tags\//} + - name: 'Create Release' + id: create_release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ env.TAG_VERSION }} + release_name: obs-websocket ${{ env.TAG_VERSION }} + draft: false + prerelease: false + - name: 'Download release artifacts' + uses: actions/download-artifact@v2-preview + - name: 'Upload Windows .zip artifact to release' + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: ${{ github.workspace }}/${{ env.TAG_VERSION }}-Windows/obs-websocket-${{ env.TAG_VERSION }}-Windows.zip + asset_name: obs-websocket-${{ env.TAG_VERSION }}-Windows.zip + asset_content_type: application/zip + - name: 'Upload Windows .exe artifact to release' + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: ${{ github.workspace }}/${{ env.TAG_VERSION }}-Windows-Installer/obs-websocket-${{ env.TAG_VERSION }}-Windows-Installer.exe + asset_name: obs-websocket-${{ env.TAG_VERSION }}-Windows-Installer.exe + asset_content_type: application/zip + - name: 'Upload Linux artifact to release' + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: ${{ github.workspace }}/${{ env.TAG_VERSION }}-linux/obs-websocket_${{ env.TAG_VERSION }}-1_amd64.deb + asset_name: obs-websocket-${{ env.TAG_VERSION }}-1_amd64.deb + asset_content_type: application/octet-stream + - name: 'Upload macOS artifact to release' + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: ${{ github.workspace }}/${{ env.TAG_VERSION }}-macOS/obs-websocket-${{ env.TAG_VERSION }}-macOS.pkg + asset_name: obs-websocket-${{ env.TAG_VERSION }}-macOS.pkg + asset_content_type: application/octet-stream diff --git a/BUILDING.md b/BUILDING.md index 83f93a99..bec47951 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -24,17 +24,23 @@ sudo apt-get install libboost-all-dev git clone --recursive https://github.com/Palakis/obs-websocket.git cd obs-websocket mkdir build && cd build -cmake -DLIBOBS_INCLUDE_DIR="" -DCMAKE_INSTALL_PREFIX=/usr .. +cmake -DLIBOBS_INCLUDE_DIR="" -DCMAKE_INSTALL_PREFIX=/usr -DUSE_UBUNTU_FIX=true .. make -j4 sudo make install ``` +On other linux OS's, use this cmake command instead: + +```shell +cmake -DLIBOBS_INCLUDE_DIR="" -DCMAKE_INSTALL_PREFIX=/usr .. +``` + ## OS X As a prerequisite, you will need Xcode for your current OSX version, the Xcode command line tools, and [Homebrew](https://brew.sh/). Homebrew's setup will guide you in getting your system set up, you should be good to go once Homebrew is successfully up and running. -Use of the Travis macOS CI scripts is recommended. Please note that these +Use of the macOS CI scripts is recommended. Please note that these scripts install new software and can change several settings on your system. An existing obs-studio development environment is not required, as `install-build-obs-macos.sh` will install it for you. If you already have a @@ -57,6 +63,4 @@ This will result in a ready-to-use `obs-websocket.pkg` installer in the `release ## Automated Builds -- Windows: [![Automated Build status for Windows](https://ci.appveyor.com/api/projects/status/github/Palakis/obs-websocket)](https://ci.appveyor.com/project/Palakis/obs-websocket/history) -- Linux: [![Automated Build status for Linux](https://travis-ci.org/Palakis/obs-websocket.svg?branch=master)](https://travis-ci.org/Palakis/obs-websocket) -- macOS: [![Automated Build status for macOS](https://img.shields.io/azure-devops/build/Palakis/obs-websocket/Palakis.obs-websocket.svg)](https://dev.azure.com/Palakis/obs-websocket/_build) +[![Build Status](https://dev.azure.com/Palakis/obs-websocket/_apis/build/status/Palakis.obs-websocket?branchName=4.x-current)](https://dev.azure.com/Palakis/obs-websocket/_build/latest?definitionId=2&branchName=4.x-current) diff --git a/CI/build-ubuntu.sh b/CI/build-ubuntu.sh index b19158ae..498840ef 100755 --- a/CI/build-ubuntu.sh +++ b/CI/build-ubuntu.sh @@ -2,5 +2,5 @@ set -ex mkdir build && cd build -cmake -DCMAKE_INSTALL_PREFIX=/usr .. +cmake -DCMAKE_INSTALL_PREFIX=/usr -DUSE_UBUNTU_FIX=true .. make -j4 diff --git a/CI/checkout-cmake-obs-windows.cmd b/CI/checkout-cmake-obs-windows.cmd deleted file mode 100644 index 0fc6c12c..00000000 --- a/CI/checkout-cmake-obs-windows.cmd +++ /dev/null @@ -1,137 +0,0 @@ -@echo off -SETLOCAL EnableDelayedExpansion - -REM Check if obs-studio build exists. -REM If the obs-studio directory does exist, check if the last OBS tag built -REM matches the latest OBS tag. -REM If the tags match, do not build obs-studio. -REM If the tags do not match, build obs-studio. -REM If the obs-studio directory doesn't exist, build obs-studio. -echo Checking for obs-studio build... - -set OBSLatestTagPrePull=0 -set OBSLatestTagPostPull=0 -echo Latest tag pre-pull: %OBSLatestTagPrePull% -echo Latest tag post-pull: %OBSLatestTagPostPull% - -REM Set up the build flag as undefined. -set "BuildOBS=" - -REM Check the last tag successfully built by CI. -if exist "%OBSPath%\obs-studio-last-tag-built.txt" ( - set /p OBSLastTagBuilt=<"%OBSPath%\obs-studio-last-tag-built.txt" -) else ( - set OBSLastTagBuilt=0 -) - -REM If obs-studio directory exists, run git pull and get the latest tag number. -if exist %OBSPath% ( - echo obs-studio directory exists - echo Updating tag info - cd /D %OBSPath% - git describe --tags --abbrev=0 --exclude="*-rc*" > "%OBSPath%\latest-obs-studio-tag-pre-pull.txt" - set /p OBSLatestTagPrePull=<"%OBSPath%\latest-obs-studio-tag-pre-pull.txt" - git checkout master - git pull - git describe --tags --abbrev=0 --exclude="*-rc*" > "%OBSPath%\latest-obs-studio-tag-post-pull.txt" - set /p OBSLatestTagPostPull=<"%OBSPath%\latest-obs-studio-tag-post-pull.txt" - set /p OBSLatestTag=<"%OBSPath%\latest-obs-studio-tag-post-pull.txt" - echo %OBSLatestTagPostPull%> "%OBSPath%\latest-obs-studio-tag.txt" -) - -REM Check the obs-studio tags for mismatches. -REM If a new tag was pulled, set the build flag. -if not %OBSLatestTagPrePull%==%OBSLatestTagPostPull% ( - echo Latest tag pre-pull: %OBSLatestTagPrePull% - echo Latest tag post-pull: %OBSLatestTagPostPull% - echo Tags do not match. Need to rebuild OBS. - set BuildOBS=true -) - -REM If the latest git tag doesn't match the last built tag, set the build flag. -if not %OBSLatestTagPostPull%==%OBSLastTagBuilt% ( - echo Last built OBS tag: %OBSLastTagBuilt% - echo Latest tag post-pull: %OBSLatestTagPostPull% - echo Tags do not match. Need to rebuild OBS. - set BuildOBS=true -) - -REM If obs-studio directory does not exist, clone the git repo, get the latest -REM tag number, and set the build flag. -if not exist %OBSPath% ( - echo obs-studio directory does not exist - git clone https://github.com/obsproject/obs-studio %OBSPath% - cd /D %OBSPath%\ - git describe --tags --abbrev=0 --exclude="*-rc*" > "%OBSPath%\obs-studio-latest-tag.txt" - set /p OBSLatestTag=<"%OBSPath%\obs-studio-latest-tag.txt" - set BuildOBS=true -) - -REM If the needed obs-studio libs for this build_config do not exist, -REM set the build flag. -if not exist %OBSPath%\build32\libobs\%build_config%\obs.lib ( - echo obs-studio\build32\libobs\%build_config%\obs.lib does not exist - set BuildOBS=true -) -if not exist %OBSPath%\build32\UI\obs-frontend-api\%build_config%\obs-frontend-api.lib ( - echo obs-studio\build32\UI\obs-frontend-api\%build_config%\obs-frontend-api.lib does not exist - set BuildOBS=true -) - -REM Some debug info -echo: -echo Latest tag pre-pull: %OBSLatestTagPrePull% -echo Latest tag post-pull: %OBSLatestTagPostPull% -echo Latest tag: %OBSLatestTag% -echo Last built OBS tag: %OBSLastTagBuilt% - -if defined BuildOBS ( - echo BuildOBS: true -) else ( - echo BuildOBS: false -) -echo: - -REM If the build flag is set, build obs-studio. -if defined BuildOBS ( - echo Building obs-studio... - cd /D %OBSPath% - echo git checkout %OBSLatestTag% - git checkout %OBSLatestTag% - echo: - - echo Removing previous build dirs... - if exist build32 rmdir /s /q "%OBSPath%\build32" - if exist build64 rmdir /s /q "%OBSPath%\build64" - - echo Making new build dirs... - mkdir build32 - mkdir build64 - - echo Running cmake for obs-studio %OBSLatestTag% 32-bit... - cd build32 - cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_SYSTEM_VERSION=10.0 -DQTDIR="%QTDIR32%" -DDepsPath="%DepsPath32%" -DBUILD_CAPTIONS=true -DDISABLE_PLUGINS=true -DCOPIED_DEPENDENCIES=false -DCOPY_DEPENDENCIES=true .. - echo: - echo: - - echo Running cmake for obs-studio %OBSLatestTag% 64-bit... - cd ..\build64 - cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_SYSTEM_VERSION=10.0 -DQTDIR="%QTDIR64%" -DDepsPath="%DepsPath64%" -DBUILD_CAPTIONS=true -DDISABLE_PLUGINS=true -DCOPIED_DEPENDENCIES=false -DCOPY_DEPENDENCIES=true .. - echo: - echo: - - REM echo Building obs-studio %OBSLatestTag% 32-bit ^(Build Config: %build_config%^)... - REM call msbuild /m /p:Configuration=%build_config% %OBSPath%\build32\obs-studio.sln - - REM echo Building obs-studio %OBSLatestTag% 64-bit ^(Build Config: %build_config%^)... - REM call msbuild /m /p:Configuration=%build_config% %OBSPath%\build64\obs-studio.sln - - cd .. - git describe --tags --abbrev=0 > "%OBSPath%\obs-studio-last-tag-built.txt" - set /p OBSLastTagBuilt=<"%OBSPath%\obs-studio-last-tag-built.txt" -) else ( - echo Last OBS tag built is: %OBSLastTagBuilt% - echo No need to rebuild OBS. -) - -dir "%OBSPath%\libobs" diff --git a/CI/install-build-obs-macos.sh b/CI/install-build-obs-macos.sh index 4af63b49..0dc610aa 100755 --- a/CI/install-build-obs-macos.sh +++ b/CI/install-build-obs-macos.sh @@ -34,6 +34,7 @@ git checkout $OBSLatestTag mkdir build && cd build echo "[obs-websocket] Building obs-studio.." cmake .. \ + -DBUILD_CAPTIONS=true \ -DCMAKE_OSX_DEPLOYMENT_TARGET=10.11 \ -DDISABLE_PLUGINS=true \ -DENABLE_SCRIPTING=0 \ diff --git a/CI/install-dependencies-macos.sh b/CI/install-dependencies-macos.sh index 0adf464b..267fa49a 100755 --- a/CI/install-dependencies-macos.sh +++ b/CI/install-dependencies-macos.sh @@ -35,13 +35,8 @@ done # qtwebsockets deps echo "[obs-websocket] Installing obs-websocket dependency 'QT 5.10.1'.." -# =!= NOTICE =!= -# When building QT5 from sources on macOS 10.13+, use local qt5 formula: -# brew install ./CI/macos/qt.rb -# Pouring from the bottle is much quicker though, so use bottle for now. -# =!= NOTICE =!= -brew install https://gist.githubusercontent.com/DDRBoxman/b3956fab6073335a4bf151db0dcbd4ad/raw/ed1342a8a86793ea8c10d8b4d712a654da121ace/qt.rb +brew install ./CI/macos/qt.rb # Pin this version of QT5 to avoid `brew upgrade` # upgrading it to incompatible version diff --git a/CI/macos/Brewfile b/CI/macos/Brewfile new file mode 100644 index 00000000..20fabb71 --- /dev/null +++ b/CI/macos/Brewfile @@ -0,0 +1,10 @@ +tap "akeru-inc/tap" +brew "jack" +brew "speexdsp" +brew "cmake" +brew "freetype" +brew "fdk-aac" +brew "https://gist.githubusercontent.com/DDRBoxman/9c7a2b08933166f4b61ed9a44b242609/raw/ef4de6c587c6bd7f50210eccd5bd51ff08e6de13/qt.rb" +brew "swig", link: false +brew "https://gist.githubusercontent.com/DDRBoxman/4cada55c51803a2f963fa40ce55c9d3e/raw/572c67e908bfbc1bcb8c476ea77ea3935133f5b5/swig.rb" +brew "akeru-inc/tap/xcnotary" \ No newline at end of file diff --git a/CI/macos/qt.rb b/CI/macos/qt.rb index 50ff4f57..4405a240 100644 --- a/CI/macos/qt.rb +++ b/CI/macos/qt.rb @@ -1,163 +1,145 @@ # Patches for Qt must be at the very least submitted to Qt's Gerrit codereview # rather than their bug-report Jira. The latter is rarely reviewed by Qt. class Qt < Formula - desc "Cross-platform application and UI framework" - homepage "https://www.qt.io/" - url "https://download.qt.io/archive/qt/5.10/5.10.1/single/qt-everywhere-src-5.10.1.tar.xz" - mirror "https://mirrorservice.org/sites/download.qt-project.org/official_releases/qt/5.10/5.10.1/single/qt-everywhere-src-5.10.1.tar.xz" - sha256 "05ffba7b811b854ed558abf2be2ddbd3bb6ddd0b60ea4b5da75d277ac15e740a" - head "https://code.qt.io/qt/qt5.git", :branch => "5.10.1", :shallow => false + desc "Cross-platform application and UI framework" + homepage "https://www.qt.io/" + url "https://download.qt.io/official_releases/qt/5.10/5.10.1/single/qt-everywhere-src-5.10.1.tar.xz" + mirror "https://www.mirrorservice.org/sites/download.qt-project.org/official_releases/qt/5.10/5.10.1/single/qt-everywhere-src-5.10.1.tar.xz" + sha256 "05ffba7b811b854ed558abf2be2ddbd3bb6ddd0b60ea4b5da75d277ac15e740a" + head "https://code.qt.io/qt/qt5.git", :branch => "5.10", :shallow => false - bottle do - sha256 "8b4bad005596a5f8790150fe455db998ac2406f4e0f04140d6656205d844d266" => :high_sierra - sha256 "9c488554935fb573554a4e36d36d3c81e47245b7fefc4b61edef894e67ba1740" => :sierra - sha256 "c0407afba5951df6cc4c6f6c1c315972bd41c99cecb4e029919c4c15ab6f7bdc" => :el_capitan - end + bottle do + sha256 "8b4bad005596a5f8790150fe455db998ac2406f4e0f04140d6656205d844d266" => :high_sierra + sha256 "9c488554935fb573554a4e36d36d3c81e47245b7fefc4b61edef894e67ba1740" => :sierra + sha256 "c0407afba5951df6cc4c6f6c1c315972bd41c99cecb4e029919c4c15ab6f7bdc" => :el_capitan + end - keg_only "Qt 5 has CMake issues when linked" + keg_only "Qt 5 has CMake issues when linked" - option "with-docs", "Build documentation" - option "with-examples", "Build examples" + option "with-docs", "Build documentation" + option "with-examples", "Build examples" + option "without-proprietary-codecs", "Don't build with proprietary codecs (e.g. mp3)" - deprecated_option "with-mysql" => "with-mysql-client" + # OS X 10.7 Lion is still supported in Qt 5.5, but is no longer a reference + # configuration and thus untested in practice. Builds on OS X 10.7 have been + # reported to fail: . + # depends_on :macos => :mountain_lion - # OS X 10.7 Lion is still supported in Qt 5.5, but is no longer a reference - # configuration and thus untested in practice. Builds on OS X 10.7 have been - # reported to fail: . - depends_on :macos => :mountain_lion + depends_on "pkg-config" => :build + depends_on :xcode => :build + depends_on "mysql" => :optional + depends_on "postgresql" => :optional - depends_on "pkg-config" => :build - depends_on :xcode => :build - depends_on "mysql-client" => :optional - depends_on "postgresql" => :optional + # Restore `.pc` files for framework-based build of Qt 5 on OS X. This + # partially reverts merged + # between the 5.5.1 and 5.6.0 releases. (Remove this as soon as feasible!) + # + # Core formulae known to fail without this patch (as of 2016-10-15): + # * gnuplot (with `--with-qt` option) + # * mkvtoolnix (with `--with-qt` option, silent build failure) + # * poppler (with `--with-qt` option) + patch do + url "https://raw.githubusercontent.com/Homebrew/formula-patches/e8fe6567/qt5/restore-pc-files.patch" + sha256 "48ff18be2f4050de7288bddbae7f47e949512ac4bcd126c2f504be2ac701158b" + end - # Restore `.pc` files for framework-based build of Qt 5 on OS X. This - # partially reverts merged - # between the 5.5.1 and 5.6.0 releases. (Remove this as soon as feasible!) - # - # Core formulae known to fail without this patch (as of 2016-10-15): - # * gnuplot (with `--with-qt` option) - # * mkvtoolnix (with `--with-qt` option, silent build failure) - # * poppler (with `--with-qt` option) - patch do - url "https://raw.githubusercontent.com/Homebrew/formula-patches/e8fe6567/qt5/restore-pc-files.patch" - sha256 "48ff18be2f4050de7288bddbae7f47e949512ac4bcd126c2f504be2ac701158b" - end + def install + args = %W[ + -verbose + -prefix #{prefix} + -release + -opensource -confirm-license + -system-zlib + -qt-libpng + -qt-libjpeg + -qt-freetype + -qt-pcre + -nomake tests + -no-rpath + -pkg-config + -dbus-runtime + ] - # Fix compile error on macOS 10.13 around QFixed: - # https://github.com/Homebrew/homebrew-core/issues/27095 - # https://bugreports.qt.io/browse/QTBUG-67545 - patch do - url "https://raw.githubusercontent.com/z00m1n/formula-patches/0de0e229/qt/QTBUG-67545.patch" - sha256 "4a115097c7582c7dce4207f5500d13feb8c990eb8a05a43f41953985976ebe6c" - end + args << "-nomake" << "examples" if build.without? "examples" - # Fix compile error on macOS 10.13 caused by qtlocation dependency - # mapbox-gl-native using Boost 1.62.0 does not build with C++ 17: - # https://github.com/Homebrew/homebrew-core/issues/27095 - # https://bugreports.qt.io/browse/QTBUG-67810 - patch do - url "https://raw.githubusercontent.com/z00m1n/formula-patches/a1a1f0dd/qt/QTBUG-67810.patch" - sha256 "8ee0bf71df1043f08ebae3aa35036be29c4d9ebff8a27e3b0411a6bd635e9382" - end + if build.with? "mysql" + args << "-plugin-sql-mysql" + (buildpath/"brew_shim/mysql_config").write <<~EOS + #!/bin/sh + if [ x"$1" = x"--libs" ]; then + mysql_config --libs | sed "s/-lssl -lcrypto//" + else + exec mysql_config "$@" + fi + EOS + chmod 0755, "brew_shim/mysql_config" + args << "-mysql_config" << buildpath/"brew_shim/mysql_config" + end - def install - args = %W[ - -verbose - -prefix #{prefix} - -release - -opensource -confirm-license - -system-zlib - -qt-libpng - -qt-libjpeg - -qt-freetype - -qt-pcre - -nomake tests - -no-rpath - -pkg-config - -dbus-runtime - -no-assimp - ] + args << "-plugin-sql-psql" if build.with? "postgresql" + args << "-proprietary-codecs" if build.with? "proprietary-codecs" - args << "-nomake" << "examples" if build.without? "examples" + system "./configure", *args + system "make" + ENV.deparallelize + system "make", "install" - if build.with? "mysql-client" - args << "-plugin-sql-mysql" - (buildpath/"brew_shim/mysql_config").write <<~EOS - #!/bin/sh - if [ x"$1" = x"--libs" ]; then - mysql_config --libs | sed "s/-lssl -lcrypto//" - else - exec mysql_config "$@" - fi - EOS - chmod 0755, "brew_shim/mysql_config" - args << "-mysql_config" << buildpath/"brew_shim/mysql_config" - end + if build.with? "docs" + system "make", "docs" + system "make", "install_docs" + end - args << "-plugin-sql-psql" if build.with? "postgresql" + # Some config scripts will only find Qt in a "Frameworks" folder + frameworks.install_symlink Dir["#{lib}/*.framework"] - system "./configure", *args - system "make" - ENV.deparallelize - system "make", "install" + # The pkg-config files installed suggest that headers can be found in the + # `include` directory. Make this so by creating symlinks from `include` to + # the Frameworks' Headers folders. + Pathname.glob("#{lib}/*.framework/Headers") do |path| + include.install_symlink path => path.parent.basename(".framework") + end - if build.with? "docs" - system "make", "docs" - system "make", "install_docs" - end + # Move `*.app` bundles into `libexec` to expose them to `brew linkapps` and + # because we don't like having them in `bin`. + # (Note: This move breaks invocation of Assistant via the Help menu + # of both Designer and Linguist as that relies on Assistant being in `bin`.) + libexec.mkpath + Pathname.glob("#{bin}/*.app") { |app| mv app, libexec } + end - # Some config scripts will only find Qt in a "Frameworks" folder - frameworks.install_symlink Dir["#{lib}/*.framework"] + def caveats; <<~EOS + We agreed to the Qt opensource license for you. + If this is unacceptable you should uninstall. + EOS + end - # The pkg-config files installed suggest that headers can be found in the - # `include` directory. Make this so by creating symlinks from `include` to - # the Frameworks' Headers folders. - Pathname.glob("#{lib}/*.framework/Headers") do |path| - include.install_symlink path => path.parent.basename(".framework") - end + test do + (testpath/"hello.pro").write <<~EOS + QT += core + QT -= gui + TARGET = hello + CONFIG += console + CONFIG -= app_bundle + TEMPLATE = app + SOURCES += main.cpp + EOS - # Move `*.app` bundles into `libexec` to expose them to `brew linkapps` and - # because we don't like having them in `bin`. - # (Note: This move breaks invocation of Assistant via the Help menu - # of both Designer and Linguist as that relies on Assistant being in `bin`.) - libexec.mkpath - Pathname.glob("#{bin}/*.app") { |app| mv app, libexec } - end + (testpath/"main.cpp").write <<~EOS + #include + #include - def caveats; <<~EOS - We agreed to the Qt opensource license for you. - If this is unacceptable you should uninstall. - EOS - end + int main(int argc, char *argv[]) + { + QCoreApplication a(argc, argv); + qDebug() << "Hello World!"; + return 0; + } + EOS - test do - (testpath/"hello.pro").write <<~EOS - QT += core - QT -= gui - TARGET = hello - CONFIG += console - CONFIG -= app_bundle - TEMPLATE = app - SOURCES += main.cpp - EOS - - (testpath/"main.cpp").write <<~EOS - #include - #include - - int main(int argc, char *argv[]) - { - QCoreApplication a(argc, argv); - qDebug() << "Hello World!"; - return 0; - } - EOS - - system bin/"qmake", testpath/"hello.pro" - system "make" - assert_predicate testpath/"hello", :exist? - assert_predicate testpath/"main.o", :exist? - system "./hello" - end -end + system bin/"qmake", testpath/"hello.pro" + system "make" + assert_predicate testpath/"hello", :exist? + assert_predicate testpath/"main.o", :exist? + system "./hello" + end +end \ No newline at end of file diff --git a/CI/prepare-obs-windows.cmd b/CI/prepare-obs-windows.cmd new file mode 100644 index 00000000..961fbe17 --- /dev/null +++ b/CI/prepare-obs-windows.cmd @@ -0,0 +1,37 @@ + +@echo off +SETLOCAL EnableDelayedExpansion + +REM If obs-studio directory does not exist, clone the git repo +if not exist %OBSPath% ( + echo obs-studio directory does not exist + git clone https://github.com/obsproject/obs-studio %OBSPath% + cd /D %OBSPath%\ + git describe --tags --abbrev=0 --exclude="*-rc*" > "%OBSPath%\obs-studio-latest-tag.txt" + set /p OBSLatestTag=<"%OBSPath%\obs-studio-latest-tag.txt" +) + +REM Prepare OBS Studio builds + +echo Running CMake... +cd /D %OBSPath% +echo git checkout %OBSLatestTag% +git checkout %OBSLatestTag% +echo: + +if not exist build32 mkdir build32 +if not exist build64 mkdir build64 + +echo Running cmake for obs-studio %OBSLatestTag% 32-bit... +cd build32 +cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_SYSTEM_VERSION=10.0 -DQTDIR="%QTDIR32%" -DDepsPath="%DepsPath32%" -DBUILD_CAPTIONS=true -DDISABLE_PLUGINS=true -DCOPIED_DEPENDENCIES=false -DCOPY_DEPENDENCIES=true .. +echo: +echo: + +echo Running cmake for obs-studio %OBSLatestTag% 64-bit... +cd ..\build64 +cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_SYSTEM_VERSION=10.0 -DQTDIR="%QTDIR64%" -DDepsPath="%DepsPath64%" -DBUILD_CAPTIONS=true -DDISABLE_PLUGINS=true -DCOPIED_DEPENDENCIES=false -DCOPY_DEPENDENCIES=true .. +echo: +echo: + +dir "%OBSPath%\libobs" \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index 5648a963..261d8c78 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,6 +11,10 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON) add_definitions(-DASIO_STANDALONE) +if (${CMAKE_SYSTEM_PROCESSOR} MATCHES "arm") + set(CMAKE_CXX_FLAGS "-mfpu=neon") +endif() + if (WIN32 OR APPLE) include(external/FindLibObs.cmake) endif() @@ -35,6 +39,7 @@ set(obs-websocket_SOURCES src/WSRequestHandler_StudioMode.cpp src/WSRequestHandler_Transitions.cpp src/WSRequestHandler_Outputs.cpp + src/WSRequestHandler_MediaControl.cpp src/WSEvents.cpp src/Config.cpp src/Utils.cpp @@ -187,6 +192,10 @@ if(UNIX AND NOT APPLE) file(GLOB locale_files data/locale/*.ini) + if(${USE_UBUNTU_FIX}) + install(TARGETS obs-websocket + LIBRARY DESTINATION "/usr/lib/obs-plugins") + endif() install(TARGETS obs-websocket LIBRARY DESTINATION "${CMAKE_INSTALL_FULL_LIBDIR}/obs-plugins") diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..f94782b9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,82 @@ +# Contributing to obs-websocket + +## Translating obs-websocket to your language + +Localization happens on [Crowdin](https://crowdin.com/project/obs-websocket) + +## Branches + +**Development happens on `4.x-current`** + +## Writing code for obs-websocket + +### Code Formatting Guidelines + +* Function and variable names: snake_case for C names, camelCase for C++ method names + +* Request and Event names should use MixedCaps names + +* Request and Event json properties should use camelCase. For more detailed info on property naming, see [Google's JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml) + +* Code is indented with Tabs. Assume they are 8 columns wide + +* 80 columns max code width. (Docs can be larger) + +* New and updated requests/events must always come with accompanying documentation comments (see existing protocol elements for examples). +These are required to automatically generate the [protocol specification document](docs/generated/protocol.md). + +### Code Best-Practices + +* Favor return-early code and avoid wrapping huge portions of code in conditionals. As an example, this: +```cpp +if (success) { + return req->SendOKResponse(); +} else { + return req->SendErrorResponse("something went wrong"); +} +``` +is better like this: +```cpp +if (!success) { + return req->SendErrorResponse("something went wrong"); +} +return req->SendOKResponse(); +``` + +* Some example common response/request property names are: + * `sceneName` - The name of a scene + * `sourceName` - The name of a source + * `fromScene` - From a scene - scene name + +### Commit Guidelines + +* Commits follow the 50/72 standard: + * 50 characters max for the commit title (excluding scope name) + * One empty line after the title + * Description wrapped to 72 columns max width per line. + +* Commit titles: + * Use present tense + * Prefix the title with a "scope" name + * e.g: "CI: fix wrong behaviour when packaging for OS X" + * Typical scopes: CI, General, Requests, Events, Server + +**Example commit:** + +``` +Requests: Add GetTransitionPosition + +Adds a new request called `GetTransitionPosition` which gets the current +transition's state from 0.0f to 1.0f. Works with both auto and manual +transitions. +``` + +### Pull Requests + +* Pull Requests must never be based off your fork's main branch (in this case, `4.x-current`). + * Start your work in a newly named branch based on the upstream main one (e.g.: `feature/cool-new-feature`, `bugfix/fix-palakis-mistakes`, ...) + +* Only open a pull request if you are ready to show off your work. + +* If your work is not done yet, but for any reason you need to PR it (like collecting discussions, testing with CI, getting testers), + create it as a Draft Pull Request (open the little arrow menu next to the "Create pull request" button, then select "Create draft pull request"). \ No newline at end of file diff --git a/README.md b/README.md index 1c210f96..741ca5cf 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,14 @@ -obs-websocket -============== +# obs-websocket + +

+ +

WebSockets API for OBS Studio. -Follow the main author on Twitter for news & updates : [@LePalakis](https://twitter.com/LePalakis) - +[![Discord](https://img.shields.io/discord/715691013825364120.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/WBaSQ3A) [![Build Status](https://dev.azure.com/Palakis/obs-websocket/_apis/build/status/Palakis.obs-websocket?branchName=4.x-current)](https://dev.azure.com/Palakis/obs-websocket/_build/latest?definitionId=2&branchName=4.x-current) +[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/fold_left.svg?style=social&label=Follow%20%40LePalakis)](https://twitter.com/LePalakis) ## Downloads @@ -13,7 +16,10 @@ Binaries for Windows, MacOS, and Linux are available in the [Releases](https://g ## Using obs-websocket -A web client and frontend made by [t2t2](https://github.com/t2t2/obs-tablet-remote) (compatible with tablets and other touch interfaces) is available here : http://t2t2.github.io/obs-tablet-remote/ +Here is a list of available web clients: (compatible with tablets and other touch interfaces) + +- [Niek/obs-web](https://github.com/Niek/obs-web) +- [t2t2/obs-tablet-remote](https://github.com/t2t2/obs-tablet-remote) It is **highly recommended** to protect obs-websocket with a password against unauthorized control. To do this, open the "Websocket server settings" dialog under OBS' "Tools" menu. In the settings dialogs, you can enable or disable authentication and set a password for it. @@ -38,7 +44,13 @@ Here's a list of available language APIs for obs-websocket : - Golang: [go-obs-websocket](https://github.com/christopher-dG/go-obs-websocket) by Chris de Graaf - HTTP API: [obs-websocket-http](https://github.com/IRLToolkit/obs-websocket-http) by tt2468 -I'd like to know what you're building with or for obs-websocket. If you do something in this fashion, feel free to drop me an email at `stephane /dot/ lepin /at/ gmail /dot/ com` ! +I'd like to know what you're building with or for obs-websocket. If you do something in this fashion, feel free to drop a message in `#project-showoff` in the [discord server!](https://discord.gg/WBaSQ3A) + +### Securing obs-websocket (via TLS/SSL) + +If you are intending to use obs-websocket outside of a LAN environment, it is highly recommended to secure the connection using a tunneling service. + +See the SSL [tunnelling guide](SSL-TUNNELLING.md) for easy instructions on how to encrypt your websocket connection. ## Compiling obs-websocket @@ -46,80 +58,23 @@ See the [build instructions](BUILDING.md). ## Contributing -### Branches - -Development happens on `4.x-current` - -### Pull Requests - -Pull Requests must never be based off your fork's main branch (in this case, `4.x-current`). Start your work in a new branch -based on the main one (e.g.: `cool-new-feature`, `fix-palakis-mistakes`, ...) and open a Pull Request once you feel ready to show your work. - -**If your Pull Request is not ready to merge yet, create it as a Draft Pull Request** (open the little arrow menu next to the "Create pull request" button, then select "Create draft pull request"). - -### Code style & formatting - -Source code is indented with tabs, with spaces allowed for alignment. - -Regarding protocol changes: new and updated request types / events must always come with accompanying documentation comments (see existing protocol elements for examples). -These are required to automatically generate the [protocol specification document](docs/generated/protocol.md). - -Among other recommendations: favor return-early code and avoid wrapping huge portions of code in conditionals. As an example, this: - -```cpp -if (success) { - return req->SendOKResponse(); -} else { - return req->SendErrorResponse("something went wrong"); -} -``` - -is better like this: - -```cpp -if (!success) { - return req->SendErrorResponse("something went wrong"); -} -return req->SendOKResponse(); -``` - +See [the contributing document](/CONTRIBUTING.md) ## Translations -**Your help is welcome on translations**. Please join the localization project on Crowdin: https://crowdin.com/project/obs-websocket +**Your help is welcome on translations.** + +Please join the localization project on [Crowdin](https://crowdin.com/project/obs-websocket) ## Special thanks -In (almost) order of appearance: - -- [Brendan H.](https://github.com/haganbmj): Code contributions and gooder English in the Protocol specification -- [Mikhail Swift](https://github.com/mikhailswift): Code contributions -- [Tobias Frahmer](https://github.com/Frahmer): Initial German localization -- [Genture](https://github.com/Genteure): Initial Simplified Chinese and Traditional Chinese localizations -- [Larissa Gabilan](https://github.com/laris151): Initial Portuguese localization -- [Andy Asquelt](https://github.com/asquelt): Initial Polish localization -- [Marcel Haazen](https://github.com/nekocentral): Initial Dutch localization -- [Peter Antonvich](https://github.com/pantonvich): Code contributions -- [yinzara](https://github.com/yinzara): Code contributions -- [Chris Angelico](https://github.com/Rosuav): Code contributions -- [Guillaume "Elektordi" Genty](https://github.com/Elektordi): Code contributions -- [Marwin M](https://github.com/dragonbane0): Code contributions -- [Logan S.](https://github.com/lsdaniel): Code contributions -- [RainbowEK](https://github.com/RainbowEK): Code contributions -- [RytoEX](https://github.com/RytoEX): CI script and code contributions -- [Theodore Stoddard](https://github.com/TStod): Code contributions -- [Philip Loche](https://github.com/PicoCentauri): Code contributions -- [Patrick Heyer](https://github.com/PatTheMav): Code contributions and CI fixes -- [Alex Van Camp](https://github.com/Lange): Code contributions -- [Freddie Meyer](https://github.com/DungFu): Code contributions -- [Casey Muller](https://github.com/caseymrm): CI fixes -- [Chris Angelico](https://github.com/Rosuav): Documentation fixes +Thank you so much to all of the contibutors [(here)](https://github.com/Palakis/obs-websocket/graphs/contributors) for your amazing help. And also: special thanks to supporters of the project! ## Supporters -They have contributed financially to the project and made possible the addition of several features into obs-websocket. Many thanks to them! +These supporters have contributed financially to the project and made possible the addition of several features into obs-websocket. Many thanks to them! --- diff --git a/SSL-TUNNELLING.md b/SSL-TUNNELLING.md new file mode 100644 index 00000000..b841e711 --- /dev/null +++ b/SSL-TUNNELLING.md @@ -0,0 +1,45 @@ +# Connecting over a TLS/secure connection (or remotely) + +If you want to expose the WebSocket server of obs-websocket over a secure TLS connection (or to connect remotely), the easiest approach is to use a localhost tunneling service like [ngrok](https://ngrok.com/) or [pagekite](https://pagekite.net/). + +**Before doing this, secure the WebSocket server first by enabling authentication with a strong password!** + +**Please bear in mind that doing this will expose your OBS instance to the open Internet and the security risks it implies. *You've been warned!*** + + +## ngrok + +[Install the ngrok CLI tool](https://ngrok.com/download) on a linux OS, then start ngrok bound to port 4444 like this: + +```bash +ngrok http 4444 +``` + +The ngrok command will output something like this: + +```text +ngrok by @inconshreveable + +Tunnel Status online +Version 2.0/2.0 +Web Interface http://127.0.0.1:4040 +Forwarding http://TUNNEL_ID.ngrok.io -> localhost:4444 +Forwarding https://TUNNEL_ID.ngrok.io -> localhost:4444 +``` + +Where `TUNNEL_ID` is, as the name implies, the unique name of your ngrok tunnel. You'll get a new one every time you start ngrok. + +Then, use `wss://TUNNEL_ID.ngrok.io` to connect to obs-websocket over TLS. + +See the [ngrok documentation](https://ngrok.com/docs) for more tunneling options and settings. + + +## PageKite + +[Install the PageKite CLI tool](http://pagekite.net/downloads), then start PageKite bound to port 4444 like this (replace NAME with one of your choosing): + +```bash +python pagekite.py 4444 NAME.pagekite.me +``` + +Then, use `wss://NAME.pagekite.me` to connect to obs-websocket over TLS. diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 0f3f10b9..bccfedb9 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -4,7 +4,7 @@ variables: trigger: branches: include: - - master + - '4.x-current' tags: include: - '*' @@ -68,7 +68,7 @@ jobs: obs | "$(Agent.OS)" path: $(OBSPath) - - script: ./CI/checkout-cmake-obs-windows.cmd + - script: ./CI/prepare-obs-windows.cmd displayName: 'Checkout & CMake OBS Studio' env: build_config: $(build_config) diff --git a/data/locale/en-US.ini b/data/locale/en-US.ini index 607ab2f2..69fbed16 100644 --- a/data/locale/en-US.ini +++ b/data/locale/en-US.ini @@ -3,6 +3,7 @@ OBSWebsocket.Settings.ServerEnable="Enable WebSockets server" OBSWebsocket.Settings.ServerPort="Server Port" OBSWebsocket.Settings.AuthRequired="Enable authentication" OBSWebsocket.Settings.Password="Password" +OBSWebsocket.Settings.LockToIPv4="Lock server to only using IPv4" OBSWebsocket.Settings.DebugEnable="Enable debug logging" OBSWebsocket.Settings.AlertsEnable="Enable System Tray Alerts" OBSWebsocket.NotifyConnect.Title="New WebSocket connection" diff --git a/docs/generated/comments.json b/docs/generated/comments.json index 28f82e48..a703f6d3 100644 --- a/docs/generated/comments.json +++ b/docs/generated/comments.json @@ -121,8 +121,8 @@ "subheads": [], "typedef": "{Object} `SceneItemTransform`", "property": [ - "{int} `position.x` The x position of the scene item from the left.", - "{int} `position.y` The y position of the scene item from the top.", + "{double} `position.x` The x position of the scene item from the left.", + "{double} `position.y` The y position of the scene item from the top.", "{int} `position.alignment` The point on the scene item that the item is manipulated from.", "{double} `rotation` The clockwise rotation of the scene item in degrees around the point of alignment.", "{double} `scale.x` The x-scale factor of the scene item.", @@ -146,12 +146,12 @@ ], "properties": [ { - "type": "int", + "type": "double", "name": "position.x", "description": "The x position of the scene item from the left." }, { - "type": "int", + "type": "double", "name": "position.y", "description": "The y position of the scene item from the top." }, @@ -561,7 +561,7 @@ }, { "subheads": [], - "description": "The scene list has been modified.\nScenes have been added, removed, or renamed.", + "description": "\n\nNote: This event is not fired when the scenes are reordered.", "api": "events", "name": "ScenesChanged", "category": "scenes", @@ -588,7 +588,7 @@ "level": 2, "text": "ScenesChanged" }, - "lead": "", + "lead": "The scene list has been modified. Scenes have been added, removed, or renamed.", "type": "class", "examples": [] }, @@ -1190,7 +1190,7 @@ }, { "subheads": [], - "description": "Emit every 2 seconds.", + "description": "Emitted every 2 seconds when stream is active.", "return": [ "{boolean} `streaming` Current streaming state.", "{boolean} `recording` Current recording state.", @@ -1730,6 +1730,7 @@ "api": "events", "name": "Heartbeat", "category": "general", + "since": "v0.3", "returns": [ { "type": "boolean", @@ -1804,6 +1805,12 @@ "description": "general" } ], + "sinces": [ + { + "name": "", + "description": "v0.3" + } + ], "heading": { "level": 2, "text": "Heartbeat" @@ -1814,7 +1821,7 @@ }, { "subheads": [], - "description": "A custom broadcast message was received", + "description": "A custom broadcast message, sent by the server, requested by one of the websocket clients.", "return": [ "{String} `realm` Identifier provided by the sender", "{Object} `data` User-defined data" @@ -2077,6 +2084,88 @@ "type": "class", "examples": [] }, + { + "subheads": [], + "description": "A source has removed audio.", + "return": "{String} `sourceName` Source name", + "api": "events", + "name": "SourceAudioDeactivated", + "category": "sources", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + } + ], + "names": [ + { + "name": "", + "description": "SourceAudioDeactivated" + } + ], + "categories": [ + { + "name": "", + "description": "sources" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "SourceAudioDeactivated" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "A source has added audio.", + "return": "{String} `sourceName` Source name", + "api": "events", + "name": "SourceAudioActivated", + "category": "sources", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + } + ], + "names": [ + { + "name": "", + "description": "SourceAudioActivated" + } + ], + "categories": [ + { + "name": "", + "description": "sources" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "SourceAudioActivated" + }, + "lead": "", + "type": "class", + "examples": [] + }, { "subheads": [], "description": "The audio sync offset of a source has changed.", @@ -2198,7 +2287,8 @@ "description": "A source has been renamed.", "return": [ "{String} `previousName` Previous source name", - "{String} `newName` New source name" + "{String} `newName` New source name", + "{String} `sourceType` Type of source (input, scene, filter, transition)" ], "api": "events", "name": "SourceRenamed", @@ -2214,6 +2304,11 @@ "type": "String", "name": "newName", "description": "New source name" + }, + { + "type": "String", + "name": "sourceType", + "description": "Type of source (input, scene, filter, transition)" } ], "names": [ @@ -2420,7 +2515,8 @@ "{String} `sourceName` Source name", "{Array} `filters` Ordered Filters list", "{String} `filters.*.name` Filter name", - "{String} `filters.*.type` Filter type" + "{String} `filters.*.type` Filter type", + "{boolean} `filters.*.enabled` Filter visibility status" ], "api": "events", "name": "SourceFiltersReordered", @@ -2446,6 +2542,11 @@ "type": "String", "name": "filters.*.type", "description": "Filter type" + }, + { + "type": "boolean", + "name": "filters.*.enabled", + "description": "Filter visibility status" } ], "names": [ @@ -2475,10 +2576,404 @@ "examples": [] } ], + "media": [ + { + "subheads": [], + "description": "\n\nNote: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaPlaying", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaPlaying" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaPlaying" + }, + "lead": "A media source has started playing.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaPaused", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaPaused" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaPaused" + }, + "lead": "A media source has been paused.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaRestarted", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaRestarted" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaRestarted" + }, + "lead": "A media source has been restarted.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaStopped", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaStopped" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaStopped" + }, + "lead": "A media source has been stopped.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaNext", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaNext" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaNext" + }, + "lead": "A media source has gone to the next item in the playlist.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaPrevious", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaPrevious" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaPrevious" + }, + "lead": "A media source has gone to the previous item in the playlist.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: These events are emitted by the OBS sources themselves. For example when the media file starts playing. The behavior depends on the type of media source being used.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaStarted", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaStarted" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaStarted" + }, + "lead": "A media source has been started.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: These events are emitted by the OBS sources themselves. For example when the media file ends. The behavior depends on the type of media source being used.", + "return": [ + "{String} `sourceName` Source name", + "{String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + ], + "api": "events", + "name": "MediaEnded", + "category": "media", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name" + }, + { + "type": "String", + "name": "sourceKind", + "description": "The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)" + } + ], + "names": [ + { + "name": "", + "description": "MediaEnded" + } + ], + "categories": [ + { + "name": "", + "description": "media" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "MediaEnded" + }, + "lead": "A media source has ended.", + "type": "class", + "examples": [] + } + ], "scene items": [ { "subheads": [], - "description": "Scene items have been reordered.", + "description": "Scene items within a scene have been reordered.", "return": [ "{String} `scene-name` Name of the scene where items have been reordered.", "{Array} `scene-items` Ordered list of scene items", @@ -2539,7 +3034,7 @@ }, { "subheads": [], - "description": "An item has been added to the current scene.", + "description": "A scene item has been added to a scene.", "return": [ "{String} `scene-name` Name of the scene.", "{String} `item-name` Name of the item added to the scene.", @@ -2594,7 +3089,7 @@ }, { "subheads": [], - "description": "An item has been removed from the current scene.", + "description": "A scene item has been removed from a scene.", "return": [ "{String} `scene-name` Name of the scene.", "{String} `item-name` Name of the item removed from the scene.", @@ -2649,7 +3144,7 @@ }, { "subheads": [], - "description": "An item's visibility has been toggled.", + "description": "A scene item's visibility has been toggled.", "return": [ "{String} `scene-name` Name of the scene.", "{String} `item-name` Name of the item in the scene.", @@ -2710,7 +3205,7 @@ }, { "subheads": [], - "description": "An item's locked status has been toggled.", + "description": "A scene item's locked status has been toggled.", "return": [ "{String} `scene-name` Name of the scene.", "{String} `item-name` Name of the item in the scene.", @@ -2771,7 +3266,7 @@ }, { "subheads": [], - "description": "An item's transform has been changed.", + "description": "A scene item's transform has been changed.", "return": [ "{String} `scene-name` Name of the scene.", "{String} `item-name` Name of the item in the scene.", @@ -3207,6 +3702,7 @@ "name": "SetHeartbeat", "category": "general", "since": "4.3.0", + "deprecated": "Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0.", "params": [ { "type": "boolean", @@ -3232,6 +3728,12 @@ "description": "4.3.0" } ], + "deprecateds": [ + { + "name": "", + "description": "Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0." + } + ], "heading": { "level": 2, "text": "SetHeartbeat" @@ -3325,7 +3827,7 @@ { "subheads": [], "description": "Get OBS stats (almost the same info as provided in OBS' stats window)", - "return": "{OBSStats} `stats` OBS stats", + "return": "{OBSStats} `stats` [OBS stats](#obsstats)", "api": "requests", "name": "GetStats", "category": "general", @@ -3334,7 +3836,7 @@ { "type": "OBSStats", "name": "stats", - "description": "OBS stats" + "description": "[OBS stats](#obsstats)" } ], "names": [ @@ -3507,9 +4009,9 @@ "subheads": [], "description": "Open a projector window or create a projector on a monitor. Requires OBS v24.0.4 or newer.", "param": [ - "{String (Optional)} `type` Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive).", + "{String (Optional)} `type` Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive).", "{int (Optional)} `monitor` Monitor to open the projector on. If -1 or omitted, opens a window.", - "{String (Optional)} `geometry` Size and position of the projector window (only if monitor is -1). Encoded in Base64 using Qt's geometry encoding (https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors.", + "{String (Optional)} `geometry` Size and position of the projector window (only if monitor is -1). Encoded in Base64 using [Qt's geometry encoding](https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors.", "{String (Optional)} `name` Name of the source or scene to be displayed (ignored for other projector types)." ], "api": "requests", @@ -3520,7 +4022,7 @@ { "type": "String (Optional)", "name": "type", - "description": "Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive)." + "description": "Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive)." }, { "type": "int (Optional)", @@ -3530,7 +4032,7 @@ { "type": "String (Optional)", "name": "geometry", - "description": "Size and position of the projector window (only if monitor is -1). Encoded in Base64 using Qt's geometry encoding (https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors." + "description": "Size and position of the projector window (only if monitor is -1). Encoded in Base64 using [Qt's geometry encoding](https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors." }, { "type": "String (Optional)", @@ -3563,94 +4065,43 @@ "lead": "", "type": "class", "examples": [] - } - ], - "outputs": [ - { - "subheads": [], - "description": "List existing outputs", - "return": "{Array} `outputs` Outputs list", - "api": "requests", - "name": "ListOutputs", - "category": "outputs", - "since": "4.7.0", - "returns": [ - { - "type": "Array", - "name": "outputs", - "description": "Outputs list" - } - ], - "names": [ - { - "name": "", - "description": "ListOutputs" - } - ], - "categories": [ - { - "name": "", - "description": "outputs" - } - ], - "sinces": [ - { - "name": "", - "description": "4.7.0" - } - ], - "heading": { - "level": 2, - "text": "ListOutputs" - }, - "lead": "", - "type": "class", - "examples": [] }, { "subheads": [], - "description": "Get information about a single output", - "param": "{String} `outputName` Output name", - "return": "{Output} `outputInfo` Output info", + "description": "Executes hotkey routine, identified by hotkey unique name", + "param": "{String} `hotkeyName` Unique name of the hotkey, as defined when registering the hotkey (e.g. \"ReplayBuffer.Save\")", "api": "requests", - "name": "GetOutputInfo", - "category": "outputs", - "since": "4.7.0", - "returns": [ - { - "type": "Output", - "name": "outputInfo", - "description": "Output info" - } - ], + "name": "TriggerHotkeyByName", + "category": "general", + "since": "unreleased", "params": [ { "type": "String", - "name": "outputName", - "description": "Output name" + "name": "hotkeyName", + "description": "Unique name of the hotkey, as defined when registering the hotkey (e.g. \"ReplayBuffer.Save\")" } ], "names": [ { "name": "", - "description": "GetOutputInfo" + "description": "TriggerHotkeyByName" } ], "categories": [ { "name": "", - "description": "outputs" + "description": "general" } ], "sinces": [ { "name": "", - "description": "4.7.0" + "description": "unreleased" } ], "heading": { "level": 2, - "text": "GetOutputInfo" + "text": "TriggerHotkeyByName" }, "lead": "", "type": "class", @@ -3658,1805 +4109,532 @@ }, { "subheads": [], - "description": "Start an output", - "param": "{String} `outputName` Output name", - "api": "requests", - "name": "StartOutput", - "category": "outputs", - "since": "4.7.0", - "params": [ - { - "type": "String", - "name": "outputName", - "description": "Output name" - } - ], - "names": [ - { - "name": "", - "description": "StartOutput" - } - ], - "categories": [ - { - "name": "", - "description": "outputs" - } - ], - "sinces": [ - { - "name": "", - "description": "4.7.0" - } - ], - "heading": { - "level": 2, - "text": "StartOutput" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Stop an output", + "description": "Executes hotkey routine, identified by bound combination of keys. A single key combination might trigger multiple hotkey routines depending on user settings", "param": [ - "{String} `outputName` Output name", - "{boolean (optional)} `force` Force stop (default: false)" + "{String} `keyId` Main key identifier (e.g. `OBS_KEY_A` for key \"A\"). Available identifiers [here](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-hotkeys.h)", + "{Object (Optional)} `keyModifiers` Optional key modifiers object. False entries can be ommitted", + "{boolean} `keyModifiers.shift` Trigger Shift Key", + "{boolean} `keyModifiers.alt` Trigger Alt Key", + "{boolean} `keyModifiers.control` Trigger Control (Ctrl) Key", + "{boolean} `keyModifiers.command` Trigger Command Key (Mac)" ], "api": "requests", - "name": "StopOutput", - "category": "outputs", - "since": "4.7.0", + "name": "TriggerHotkeyBySequence", + "category": "general", + "since": "unreleased", "params": [ { "type": "String", - "name": "outputName", - "description": "Output name" + "name": "keyId", + "description": "Main key identifier (e.g. `OBS_KEY_A` for key \"A\"). Available identifiers [here](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-hotkeys.h)" }, { - "type": "boolean (optional)", - "name": "force", - "description": "Force stop (default: false)" - } - ], - "names": [ - { - "name": "", - "description": "StopOutput" - } - ], - "categories": [ - { - "name": "", - "description": "outputs" - } - ], - "sinces": [ - { - "name": "", - "description": "4.7.0" - } - ], - "heading": { - "level": 2, - "text": "StopOutput" - }, - "lead": "", - "type": "class", - "examples": [] - } - ], - "profiles": [ - { - "subheads": [], - "description": "Set the currently active profile.", - "param": "{String} `profile-name` Name of the desired profile.", - "api": "requests", - "name": "SetCurrentProfile", - "category": "profiles", - "since": "4.0.0", - "params": [ - { - "type": "String", - "name": "profile-name", - "description": "Name of the desired profile." - } - ], - "names": [ - { - "name": "", - "description": "SetCurrentProfile" - } - ], - "categories": [ - { - "name": "", - "description": "profiles" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "heading": { - "level": 2, - "text": "SetCurrentProfile" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Get the name of the current profile.", - "return": "{String} `profile-name` Name of the currently active profile.", - "api": "requests", - "name": "GetCurrentProfile", - "category": "profiles", - "since": "4.0.0", - "returns": [ - { - "type": "String", - "name": "profile-name", - "description": "Name of the currently active profile." - } - ], - "names": [ - { - "name": "", - "description": "GetCurrentProfile" - } - ], - "categories": [ - { - "name": "", - "description": "profiles" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "heading": { - "level": 2, - "text": "GetCurrentProfile" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Get a list of available profiles.", - "return": "{Array} `profiles` List of available profiles.", - "api": "requests", - "name": "ListProfiles", - "category": "profiles", - "since": "4.0.0", - "returns": [ - { - "type": "Array", - "name": "profiles", - "description": "List of available profiles." - } - ], - "names": [ - { - "name": "", - "description": "ListProfiles" - } - ], - "categories": [ - { - "name": "", - "description": "profiles" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "heading": { - "level": 2, - "text": "ListProfiles" - }, - "lead": "", - "type": "class", - "examples": [] - } - ], - "recording": [ - { - "subheads": [], - "description": "Toggle recording on or off.", - "api": "requests", - "name": "StartStopRecording", - "category": "recording", - "since": "0.3", - "names": [ - { - "name": "", - "description": "StartStopRecording" - } - ], - "categories": [ - { - "name": "", - "description": "recording" - } - ], - "sinces": [ - { - "name": "", - "description": "0.3" - } - ], - "heading": { - "level": 2, - "text": "StartStopRecording" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Start recording.\nWill return an `error` if recording is already active.", - "api": "requests", - "name": "StartRecording", - "category": "recording", - "since": "4.1.0", - "names": [ - { - "name": "", - "description": "StartRecording" - } - ], - "categories": [ - { - "name": "", - "description": "recording" - } - ], - "sinces": [ - { - "name": "", - "description": "4.1.0" - } - ], - "heading": { - "level": 2, - "text": "StartRecording" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Stop recording.\nWill return an `error` if recording is not active.", - "api": "requests", - "name": "StopRecording", - "category": "recording", - "since": "4.1.0", - "names": [ - { - "name": "", - "description": "StopRecording" - } - ], - "categories": [ - { - "name": "", - "description": "recording" - } - ], - "sinces": [ - { - "name": "", - "description": "4.1.0" - } - ], - "heading": { - "level": 2, - "text": "StopRecording" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Pause the current recording.\nReturns an error if recording is not active or already paused.", - "api": "requests", - "name": "PauseRecording", - "category": "recording", - "since": "4.7.0", - "names": [ - { - "name": "", - "description": "PauseRecording" - } - ], - "categories": [ - { - "name": "", - "description": "recording" - } - ], - "sinces": [ - { - "name": "", - "description": "4.7.0" - } - ], - "heading": { - "level": 2, - "text": "PauseRecording" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Resume/unpause the current recording (if paused).\nReturns an error if recording is not active or not paused.", - "api": "requests", - "name": "ResumeRecording", - "category": "recording", - "since": "4.7.0", - "names": [ - { - "name": "", - "description": "ResumeRecording" - } - ], - "categories": [ - { - "name": "", - "description": "recording" - } - ], - "sinces": [ - { - "name": "", - "description": "4.7.0" - } - ], - "heading": { - "level": 2, - "text": "ResumeRecording" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "\n\nPlease note: if `SetRecordingFolder` is called while a recording is\nin progress, the change won't be applied immediately and will be\neffective on the next recording.", - "param": "{String} `rec-folder` Path of the recording folder.", - "api": "requests", - "name": "SetRecordingFolder", - "category": "recording", - "since": "4.1.0", - "params": [ - { - "type": "String", - "name": "rec-folder", - "description": "Path of the recording folder." - } - ], - "names": [ - { - "name": "", - "description": "SetRecordingFolder" - } - ], - "categories": [ - { - "name": "", - "description": "recording" - } - ], - "sinces": [ - { - "name": "", - "description": "4.1.0" - } - ], - "heading": { - "level": 2, - "text": "SetRecordingFolder" - }, - "lead": "In the current profile, sets the recording folder of the Simple and Advanced output modes to the specified value.", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Get the path of the current recording folder.", - "return": "{String} `rec-folder` Path of the recording folder.", - "api": "requests", - "name": "GetRecordingFolder", - "category": "recording", - "since": "4.1.0", - "returns": [ - { - "type": "String", - "name": "rec-folder", - "description": "Path of the recording folder." - } - ], - "names": [ - { - "name": "", - "description": "GetRecordingFolder" - } - ], - "categories": [ - { - "name": "", - "description": "recording" - } - ], - "sinces": [ - { - "name": "", - "description": "4.1.0" - } - ], - "heading": { - "level": 2, - "text": "GetRecordingFolder" - }, - "lead": "", - "type": "class", - "examples": [] - } - ], - "replay buffer": [ - { - "subheads": [], - "description": "Toggle the Replay Buffer on/off.", - "api": "requests", - "name": "StartStopReplayBuffer", - "category": "replay buffer", - "since": "4.2.0", - "names": [ - { - "name": "", - "description": "StartStopReplayBuffer" - } - ], - "categories": [ - { - "name": "", - "description": "replay buffer" - } - ], - "sinces": [ - { - "name": "", - "description": "4.2.0" - } - ], - "heading": { - "level": 2, - "text": "StartStopReplayBuffer" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Start recording into the Replay Buffer.\nWill return an `error` if the Replay Buffer is already active or if the\n\"Save Replay Buffer\" hotkey is not set in OBS' settings.\nSetting this hotkey is mandatory, even when triggering saves only\nthrough obs-websocket.", - "api": "requests", - "name": "StartReplayBuffer", - "category": "replay buffer", - "since": "4.2.0", - "names": [ - { - "name": "", - "description": "StartReplayBuffer" - } - ], - "categories": [ - { - "name": "", - "description": "replay buffer" - } - ], - "sinces": [ - { - "name": "", - "description": "4.2.0" - } - ], - "heading": { - "level": 2, - "text": "StartReplayBuffer" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Stop recording into the Replay Buffer.\nWill return an `error` if the Replay Buffer is not active.", - "api": "requests", - "name": "StopReplayBuffer", - "category": "replay buffer", - "since": "4.2.0", - "names": [ - { - "name": "", - "description": "StopReplayBuffer" - } - ], - "categories": [ - { - "name": "", - "description": "replay buffer" - } - ], - "sinces": [ - { - "name": "", - "description": "4.2.0" - } - ], - "heading": { - "level": 2, - "text": "StopReplayBuffer" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Flush and save the contents of the Replay Buffer to disk. This is\nbasically the same as triggering the \"Save Replay Buffer\" hotkey.\nWill return an `error` if the Replay Buffer is not active.", - "api": "requests", - "name": "SaveReplayBuffer", - "category": "replay buffer", - "since": "4.2.0", - "names": [ - { - "name": "", - "description": "SaveReplayBuffer" - } - ], - "categories": [ - { - "name": "", - "description": "replay buffer" - } - ], - "sinces": [ - { - "name": "", - "description": "4.2.0" - } - ], - "heading": { - "level": 2, - "text": "SaveReplayBuffer" - }, - "lead": "", - "type": "class", - "examples": [] - } - ], - "scene collections": [ - { - "subheads": [], - "description": "Change the active scene collection.", - "param": "{String} `sc-name` Name of the desired scene collection.", - "api": "requests", - "name": "SetCurrentSceneCollection", - "category": "scene collections", - "since": "4.0.0", - "params": [ - { - "type": "String", - "name": "sc-name", - "description": "Name of the desired scene collection." - } - ], - "names": [ - { - "name": "", - "description": "SetCurrentSceneCollection" - } - ], - "categories": [ - { - "name": "", - "description": "scene collections" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "heading": { - "level": 2, - "text": "SetCurrentSceneCollection" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Get the name of the current scene collection.", - "return": "{String} `sc-name` Name of the currently active scene collection.", - "api": "requests", - "name": "GetCurrentSceneCollection", - "category": "scene collections", - "since": "4.0.0", - "returns": [ - { - "type": "String", - "name": "sc-name", - "description": "Name of the currently active scene collection." - } - ], - "names": [ - { - "name": "", - "description": "GetCurrentSceneCollection" - } - ], - "categories": [ - { - "name": "", - "description": "scene collections" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "heading": { - "level": 2, - "text": "GetCurrentSceneCollection" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "List available scene collections", - "return": "{Array} `scene-collections` Scene collections list", - "api": "requests", - "name": "ListSceneCollections", - "category": "scene collections", - "since": "4.0.0", - "returns": [ - { - "type": "Array", - "name": "scene-collections", - "description": "Scene collections list" - } - ], - "names": [ - { - "name": "", - "description": "ListSceneCollections" - } - ], - "categories": [ - { - "name": "", - "description": "scene collections" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "heading": { - "level": 2, - "text": "ListSceneCollections" - }, - "lead": "", - "type": "class", - "examples": [] - } - ], - "scene items": [ - { - "subheads": [], - "description": "Gets the scene specific properties of the specified source item.\nCoordinates are relative to the item's parent (the scene or group it belongs to).", - "param": [ - "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", - "{String | Object} `item` Scene Item name (if this field is a string) or specification (if it is an object).", - "{String (optional)} `item.name` Scene Item name (if the `item` field is an object)", - "{int (optional)} `item.id` Scene Item ID (if the `item` field is an object)" - ], - "return": [ - "{String} `name` Scene Item name.", - "{int} `itemId` Scene Item ID.", - "{int} `position.x` The x position of the source from the left.", - "{int} `position.y` The y position of the source from the top.", - "{int} `position.alignment` The point on the source that the item is manipulated from.", - "{double} `rotation` The clockwise rotation of the item in degrees around the point of alignment.", - "{double} `scale.x` The x-scale factor of the source.", - "{double} `scale.y` The y-scale factor of the source.", - "{int} `crop.top` The number of pixels cropped off the top of the source before scaling.", - "{int} `crop.right` The number of pixels cropped off the right of the source before scaling.", - "{int} `crop.bottom` The number of pixels cropped off the bottom of the source before scaling.", - "{int} `crop.left` The number of pixels cropped off the left of the source before scaling.", - "{bool} `visible` If the source is visible.", - "{bool} `muted` If the source is muted.", - "{bool} `locked` If the source's transform is locked.", - "{String} `bounds.type` Type of bounding box. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\".", - "{int} `bounds.alignment` Alignment of the bounding box.", - "{double} `bounds.x` Width of the bounding box.", - "{double} `bounds.y` Height of the bounding box.", - "{int} `sourceWidth` Base width (without scaling) of the source", - "{int} `sourceHeight` Base source (without scaling) of the source", - "{double} `width` Scene item width (base source width multiplied by the horizontal scaling factor)", - "{double} `height` Scene item height (base source height multiplied by the vertical scaling factor)", - "{int} `alignment` The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis.", - "{String (optional)} `parentGroupName` Name of the item's parent (if this item belongs to a group)", - "{Array (optional)} `groupChildren` List of children (if this item is a group)" - ], - "api": "requests", - "name": "GetSceneItemProperties", - "category": "scene items", - "since": "4.3.0", - "returns": [ - { - "type": "String", - "name": "name", - "description": "Scene Item name." - }, - { - "type": "int", - "name": "itemId", - "description": "Scene Item ID." - }, - { - "type": "int", - "name": "position.x", - "description": "The x position of the source from the left." - }, - { - "type": "int", - "name": "position.y", - "description": "The y position of the source from the top." - }, - { - "type": "int", - "name": "position.alignment", - "description": "The point on the source that the item is manipulated from." - }, - { - "type": "double", - "name": "rotation", - "description": "The clockwise rotation of the item in degrees around the point of alignment." - }, - { - "type": "double", - "name": "scale.x", - "description": "The x-scale factor of the source." - }, - { - "type": "double", - "name": "scale.y", - "description": "The y-scale factor of the source." - }, - { - "type": "int", - "name": "crop.top", - "description": "The number of pixels cropped off the top of the source before scaling." - }, - { - "type": "int", - "name": "crop.right", - "description": "The number of pixels cropped off the right of the source before scaling." - }, - { - "type": "int", - "name": "crop.bottom", - "description": "The number of pixels cropped off the bottom of the source before scaling." - }, - { - "type": "int", - "name": "crop.left", - "description": "The number of pixels cropped off the left of the source before scaling." - }, - { - "type": "bool", - "name": "visible", - "description": "If the source is visible." - }, - { - "type": "bool", - "name": "muted", - "description": "If the source is muted." - }, - { - "type": "bool", - "name": "locked", - "description": "If the source's transform is locked." - }, - { - "type": "String", - "name": "bounds.type", - "description": "Type of bounding box. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\"." - }, - { - "type": "int", - "name": "bounds.alignment", - "description": "Alignment of the bounding box." - }, - { - "type": "double", - "name": "bounds.x", - "description": "Width of the bounding box." - }, - { - "type": "double", - "name": "bounds.y", - "description": "Height of the bounding box." - }, - { - "type": "int", - "name": "sourceWidth", - "description": "Base width (without scaling) of the source" - }, - { - "type": "int", - "name": "sourceHeight", - "description": "Base source (without scaling) of the source" - }, - { - "type": "double", - "name": "width", - "description": "Scene item width (base source width multiplied by the horizontal scaling factor)" - }, - { - "type": "double", - "name": "height", - "description": "Scene item height (base source height multiplied by the vertical scaling factor)" - }, - { - "type": "int", - "name": "alignment", - "description": "The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis." - }, - { - "type": "String (optional)", - "name": "parentGroupName", - "description": "Name of the item's parent (if this item belongs to a group)" - }, - { - "type": "Array (optional)", - "name": "groupChildren", - "description": "List of children (if this item is a group)" - } - ], - "params": [ - { - "type": "String (optional)", - "name": "scene-name", - "description": "Name of the scene the scene item belongs to. Defaults to the current scene." - }, - { - "type": "String | Object", - "name": "item", - "description": "Scene Item name (if this field is a string) or specification (if it is an object)." - }, - { - "type": "String (optional)", - "name": "item.name", - "description": "Scene Item name (if the `item` field is an object)" - }, - { - "type": "int (optional)", - "name": "item.id", - "description": "Scene Item ID (if the `item` field is an object)" - } - ], - "names": [ - { - "name": "", - "description": "GetSceneItemProperties" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.3.0" - } - ], - "heading": { - "level": 2, - "text": "GetSceneItemProperties" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Sets the scene specific properties of a source. Unspecified properties will remain unchanged.\nCoordinates are relative to the item's parent (the scene or group it belongs to).", - "param": [ - "{String (optional)} `scene-name` Name of the scene the source item belongs to. Defaults to the current scene.", - "{String | Object} `item` Scene Item name (if this field is a string) or specification (if it is an object).", - "{String (optional)} `item.name` Scene Item name (if the `item` field is an object)", - "{int (optional)} `item.id` Scene Item ID (if the `item` field is an object)", - "{int (optional)} `position.x` The new x position of the source.", - "{int (optional)} `position.y` The new y position of the source.", - "{int (optional)} `position.alignment` The new alignment of the source.", - "{double (optional)} `rotation` The new clockwise rotation of the item in degrees.", - "{double (optional)} `scale.x` The new x scale of the item.", - "{double (optional)} `scale.y` The new y scale of the item.", - "{int (optional)} `crop.top` The new amount of pixels cropped off the top of the source before scaling.", - "{int (optional)} `crop.bottom` The new amount of pixels cropped off the bottom of the source before scaling.", - "{int (optional)} `crop.left` The new amount of pixels cropped off the left of the source before scaling.", - "{int (optional)} `crop.right` The new amount of pixels cropped off the right of the source before scaling.", - "{bool (optional)} `visible` The new visibility of the source. 'true' shows source, 'false' hides source.", - "{bool (optional)} `locked` The new locked status of the source. 'true' keeps it in its current position, 'false' allows movement.", - "{String (optional)} `bounds.type` The new bounds type of the source. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\".", - "{int (optional)} `bounds.alignment` The new alignment of the bounding box. (0-2, 4-6, 8-10)", - "{double (optional)} `bounds.x` The new width of the bounding box.", - "{double (optional)} `bounds.y` The new height of the bounding box." - ], - "api": "requests", - "name": "SetSceneItemProperties", - "category": "scene items", - "since": "4.3.0", - "params": [ - { - "type": "String (optional)", - "name": "scene-name", - "description": "Name of the scene the source item belongs to. Defaults to the current scene." - }, - { - "type": "String | Object", - "name": "item", - "description": "Scene Item name (if this field is a string) or specification (if it is an object)." - }, - { - "type": "String (optional)", - "name": "item.name", - "description": "Scene Item name (if the `item` field is an object)" - }, - { - "type": "int (optional)", - "name": "item.id", - "description": "Scene Item ID (if the `item` field is an object)" - }, - { - "type": "int (optional)", - "name": "position.x", - "description": "The new x position of the source." - }, - { - "type": "int (optional)", - "name": "position.y", - "description": "The new y position of the source." - }, - { - "type": "int (optional)", - "name": "position.alignment", - "description": "The new alignment of the source." - }, - { - "type": "double (optional)", - "name": "rotation", - "description": "The new clockwise rotation of the item in degrees." - }, - { - "type": "double (optional)", - "name": "scale.x", - "description": "The new x scale of the item." - }, - { - "type": "double (optional)", - "name": "scale.y", - "description": "The new y scale of the item." - }, - { - "type": "int (optional)", - "name": "crop.top", - "description": "The new amount of pixels cropped off the top of the source before scaling." - }, - { - "type": "int (optional)", - "name": "crop.bottom", - "description": "The new amount of pixels cropped off the bottom of the source before scaling." - }, - { - "type": "int (optional)", - "name": "crop.left", - "description": "The new amount of pixels cropped off the left of the source before scaling." - }, - { - "type": "int (optional)", - "name": "crop.right", - "description": "The new amount of pixels cropped off the right of the source before scaling." - }, - { - "type": "bool (optional)", - "name": "visible", - "description": "The new visibility of the source. 'true' shows source, 'false' hides source." - }, - { - "type": "bool (optional)", - "name": "locked", - "description": "The new locked status of the source. 'true' keeps it in its current position, 'false' allows movement." - }, - { - "type": "String (optional)", - "name": "bounds.type", - "description": "The new bounds type of the source. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\"." - }, - { - "type": "int (optional)", - "name": "bounds.alignment", - "description": "The new alignment of the bounding box. (0-2, 4-6, 8-10)" - }, - { - "type": "double (optional)", - "name": "bounds.x", - "description": "The new width of the bounding box." - }, - { - "type": "double (optional)", - "name": "bounds.y", - "description": "The new height of the bounding box." - } - ], - "names": [ - { - "name": "", - "description": "SetSceneItemProperties" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.3.0" - } - ], - "heading": { - "level": 2, - "text": "SetSceneItemProperties" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Reset a scene item.", - "param": [ - "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", - "{String | Object} `item` Scene Item name (if this field is a string) or specification (if it is an object).", - "{String (optional)} `item.name` Scene Item name (if the `item` field is an object)", - "{int (optional)} `item.id` Scene Item ID (if the `item` field is an object)" - ], - "api": "requests", - "name": "ResetSceneItem", - "category": "scene items", - "since": "4.2.0", - "params": [ - { - "type": "String (optional)", - "name": "scene-name", - "description": "Name of the scene the scene item belongs to. Defaults to the current scene." - }, - { - "type": "String | Object", - "name": "item", - "description": "Scene Item name (if this field is a string) or specification (if it is an object)." - }, - { - "type": "String (optional)", - "name": "item.name", - "description": "Scene Item name (if the `item` field is an object)" - }, - { - "type": "int (optional)", - "name": "item.id", - "description": "Scene Item ID (if the `item` field is an object)" - } - ], - "names": [ - { - "name": "", - "description": "ResetSceneItem" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.2.0" - } - ], - "heading": { - "level": 2, - "text": "ResetSceneItem" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Show or hide a specified source item in a specified scene.", - "param": [ - "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the currently active scene.", - "{String} `source` Scene Item name.", - "{boolean} `render` true = shown ; false = hidden" - ], - "api": "requests", - "name": "SetSceneItemRender", - "category": "scene items", - "since": "0.3", - "deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.", - "params": [ - { - "type": "String (optional)", - "name": "scene-name", - "description": "Name of the scene the scene item belongs to. Defaults to the currently active scene." - }, - { - "type": "String", - "name": "source", - "description": "Scene Item name." + "type": "Object (Optional)", + "name": "keyModifiers", + "description": "Optional key modifiers object. False entries can be ommitted" }, { "type": "boolean", - "name": "render", - "description": "true = shown ; false = hidden" + "name": "keyModifiers.shift", + "description": "Trigger Shift Key" + }, + { + "type": "boolean", + "name": "keyModifiers.alt", + "description": "Trigger Alt Key" + }, + { + "type": "boolean", + "name": "keyModifiers.control", + "description": "Trigger Control (Ctrl) Key" + }, + { + "type": "boolean", + "name": "keyModifiers.command", + "description": "Trigger Command Key (Mac)" } ], "names": [ { "name": "", - "description": "SetSceneItemRender" + "description": "TriggerHotkeyBySequence" } ], "categories": [ { "name": "", - "description": "scene items" + "description": "general" } ], "sinces": [ { "name": "", - "description": "0.3" - } - ], - "deprecateds": [ - { - "name": "", - "description": "Since 4.3.0. Prefer the use of SetSceneItemProperties." + "description": "unreleased" } ], "heading": { "level": 2, - "text": "SetSceneItemRender" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Sets the coordinates of a specified source item.", - "param": [ - "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", - "{String} `item` Scene Item name.", - "{double} `x` X coordinate.", - "{double} `y` Y coordinate." - ], - "api": "requests", - "name": "SetSceneItemPosition", - "category": "scene items", - "since": "4.0.0", - "deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.", - "params": [ - { - "type": "String (optional)", - "name": "scene-name", - "description": "Name of the scene the scene item belongs to. Defaults to the current scene." - }, - { - "type": "String", - "name": "item", - "description": "Scene Item name." - }, - { - "type": "double", - "name": "x", - "description": "X coordinate." - }, - { - "type": "double", - "name": "y", - "description": "Y coordinate." - } - ], - "names": [ - { - "name": "", - "description": "SetSceneItemPosition" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "deprecateds": [ - { - "name": "", - "description": "Since 4.3.0. Prefer the use of SetSceneItemProperties." - } - ], - "heading": { - "level": 2, - "text": "SetSceneItemPosition" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Set the transform of the specified source item.", - "param": [ - "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", - "{String} `item` Scene Item name.", - "{double} `x-scale` Width scale factor.", - "{double} `y-scale` Height scale factor.", - "{double} `rotation` Source item rotation (in degrees)." - ], - "api": "requests", - "name": "SetSceneItemTransform", - "category": "scene items", - "since": "4.0.0", - "deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.", - "params": [ - { - "type": "String (optional)", - "name": "scene-name", - "description": "Name of the scene the scene item belongs to. Defaults to the current scene." - }, - { - "type": "String", - "name": "item", - "description": "Scene Item name." - }, - { - "type": "double", - "name": "x-scale", - "description": "Width scale factor." - }, - { - "type": "double", - "name": "y-scale", - "description": "Height scale factor." - }, - { - "type": "double", - "name": "rotation", - "description": "Source item rotation (in degrees)." - } - ], - "names": [ - { - "name": "", - "description": "SetSceneItemTransform" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.0.0" - } - ], - "deprecateds": [ - { - "name": "", - "description": "Since 4.3.0. Prefer the use of SetSceneItemProperties." - } - ], - "heading": { - "level": 2, - "text": "SetSceneItemTransform" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Sets the crop coordinates of the specified source item.", - "param": [ - "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", - "{String} `item` Scene Item name.", - "{int} `top` Pixel position of the top of the source item.", - "{int} `bottom` Pixel position of the bottom of the source item.", - "{int} `left` Pixel position of the left of the source item.", - "{int} `right` Pixel position of the right of the source item." - ], - "api": "requests", - "name": "SetSceneItemCrop", - "category": "scene items", - "since": "4.1.0", - "deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.", - "params": [ - { - "type": "String (optional)", - "name": "scene-name", - "description": "Name of the scene the scene item belongs to. Defaults to the current scene." - }, - { - "type": "String", - "name": "item", - "description": "Scene Item name." - }, - { - "type": "int", - "name": "top", - "description": "Pixel position of the top of the source item." - }, - { - "type": "int", - "name": "bottom", - "description": "Pixel position of the bottom of the source item." - }, - { - "type": "int", - "name": "left", - "description": "Pixel position of the left of the source item." - }, - { - "type": "int", - "name": "right", - "description": "Pixel position of the right of the source item." - } - ], - "names": [ - { - "name": "", - "description": "SetSceneItemCrop" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.1.0" - } - ], - "deprecateds": [ - { - "name": "", - "description": "Since 4.3.0. Prefer the use of SetSceneItemProperties." - } - ], - "heading": { - "level": 2, - "text": "SetSceneItemCrop" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Deletes a scene item.", - "param": [ - "{String (optional)} `scene` Name of the scene the scene item belongs to. Defaults to the current scene.", - "{Object} `item` Scene item to delete (required)", - "{String} `item.name` Scene Item name (prefer `id`, including both is acceptable).", - "{int} `item.id` Scene Item ID." - ], - "api": "requests", - "name": "DeleteSceneItem", - "category": "scene items", - "since": "4.5.0", - "params": [ - { - "type": "String (optional)", - "name": "scene", - "description": "Name of the scene the scene item belongs to. Defaults to the current scene." - }, - { - "type": "Object", - "name": "item", - "description": "Scene item to delete (required)" - }, - { - "type": "String", - "name": "item.name", - "description": "Scene Item name (prefer `id`, including both is acceptable)." - }, - { - "type": "int", - "name": "item.id", - "description": "Scene Item ID." - } - ], - "names": [ - { - "name": "", - "description": "DeleteSceneItem" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.5.0" - } - ], - "heading": { - "level": 2, - "text": "DeleteSceneItem" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Duplicates a scene item.", - "param": [ - "{String (optional)} `fromScene` Name of the scene to copy the item from. Defaults to the current scene.", - "{String (optional)} `toScene` Name of the scene to create the item in. Defaults to the current scene.", - "{Object} `item` Scene Item to duplicate from the source scene (required)", - "{String} `item.name` Scene Item name (prefer `id`, including both is acceptable).", - "{int} `item.id` Scene Item ID." - ], - "return": [ - "{String} `scene` Name of the scene where the new item was created", - "{Object} `item` New item info", - "{int} `item.id` New item ID", - "{String} `item.name` New item name" - ], - "api": "requests", - "name": "DuplicateSceneItem", - "category": "scene items", - "since": "4.5.0", - "returns": [ - { - "type": "String", - "name": "scene", - "description": "Name of the scene where the new item was created" - }, - { - "type": "Object", - "name": "item", - "description": "New item info" - }, - { - "type": "int", - "name": "item.id", - "description": "New item ID" - }, - { - "type": "String", - "name": "item.name", - "description": "New item name" - } - ], - "params": [ - { - "type": "String (optional)", - "name": "fromScene", - "description": "Name of the scene to copy the item from. Defaults to the current scene." - }, - { - "type": "String (optional)", - "name": "toScene", - "description": "Name of the scene to create the item in. Defaults to the current scene." - }, - { - "type": "Object", - "name": "item", - "description": "Scene Item to duplicate from the source scene (required)" - }, - { - "type": "String", - "name": "item.name", - "description": "Scene Item name (prefer `id`, including both is acceptable)." - }, - { - "type": "int", - "name": "item.id", - "description": "Scene Item ID." - } - ], - "names": [ - { - "name": "", - "description": "DuplicateSceneItem" - } - ], - "categories": [ - { - "name": "", - "description": "scene items" - } - ], - "sinces": [ - { - "name": "", - "description": "4.5.0" - } - ], - "heading": { - "level": 2, - "text": "DuplicateSceneItem" + "text": "TriggerHotkeyBySequence" }, "lead": "", "type": "class", "examples": [] } ], - "scenes": [ + "media control": [ { "subheads": [], - "description": "Switch to the specified scene.", - "param": "{String} `scene-name` Name of the scene to switch to.", - "api": "requests", - "name": "SetCurrentScene", - "category": "scenes", - "since": "0.3", - "params": [ - { - "type": "String", - "name": "scene-name", - "description": "Name of the scene to switch to." - } - ], - "names": [ - { - "name": "", - "description": "SetCurrentScene" - } - ], - "categories": [ - { - "name": "", - "description": "scenes" - } - ], - "sinces": [ - { - "name": "", - "description": "0.3" - } - ], - "heading": { - "level": 2, - "text": "SetCurrentScene" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Get the current scene's name and source items.", - "return": [ - "{String} `name` Name of the currently active scene.", - "{Array} `sources` Ordered list of the current scene's source items." - ], - "api": "requests", - "name": "GetCurrentScene", - "category": "scenes", - "since": "0.3", - "returns": [ - { - "type": "String", - "name": "name", - "description": "Name of the currently active scene." - }, - { - "type": "Array", - "name": "sources", - "description": "Ordered list of the current scene's source items." - } - ], - "names": [ - { - "name": "", - "description": "GetCurrentScene" - } - ], - "categories": [ - { - "name": "", - "description": "scenes" - } - ], - "sinces": [ - { - "name": "", - "description": "0.3" - } - ], - "heading": { - "level": 2, - "text": "GetCurrentScene" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Get a list of scenes in the currently active profile.", - "return": [ - "{String} `current-scene` Name of the currently active scene.", - "{Array} `scenes` Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information)." - ], - "api": "requests", - "name": "GetSceneList", - "category": "scenes", - "since": "0.3", - "returns": [ - { - "type": "String", - "name": "current-scene", - "description": "Name of the currently active scene." - }, - { - "type": "Array", - "name": "scenes", - "description": "Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information)." - } - ], - "names": [ - { - "name": "", - "description": "GetSceneList" - } - ], - "categories": [ - { - "name": "", - "description": "scenes" - } - ], - "sinces": [ - { - "name": "", - "description": "0.3" - } - ], - "heading": { - "level": 2, - "text": "GetSceneList" - }, - "lead": "", - "type": "class", - "examples": [] - }, - { - "subheads": [], - "description": "Changes the order of scene items in the requested scene.", + "description": "Pause or play a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)", "param": [ - "{String (optional)} `scene` Name of the scene to reorder (defaults to current).", - "{Array} `items` Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene", - "{int (optional)} `items[].id` Id of a specific scene item. Unique on a scene by scene basis.", - "{String (optional)} `items[].name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene." + "{String} `sourceName` Source name.", + "{boolean} `playPause` Whether to pause or play the source. `false` for play, `true` for pause." ], "api": "requests", - "name": "ReorderSceneItems", - "category": "scenes", - "since": "4.5.0", + "name": "PlayPauseMedia", + "category": "media control", + "since": "unreleased", "params": [ { - "type": "String (optional)", - "name": "scene", - "description": "Name of the scene to reorder (defaults to current)." + "type": "String", + "name": "sourceName", + "description": "Source name." }, { - "type": "Array", - "name": "items", - "description": "Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene" - }, - { - "type": "int (optional)", - "name": "items[].id", - "description": "Id of a specific scene item. Unique on a scene by scene basis." - }, - { - "type": "String (optional)", - "name": "items[].name", - "description": "Name of a scene item. Sufficiently unique if no scene items share sources within the scene." + "type": "boolean", + "name": "playPause", + "description": "Whether to pause or play the source. `false` for play, `true` for pause." } ], "names": [ { "name": "", - "description": "ReorderSceneItems" + "description": "PlayPauseMedia" } ], "categories": [ { "name": "", - "description": "scenes" + "description": "media control" } ], "sinces": [ { "name": "", - "description": "4.5.0" + "description": "unreleased" } ], "heading": { "level": 2, - "text": "ReorderSceneItems" + "text": "PlayPauseMedia" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Restart a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)", + "param": "{String} `sourceName` Source name.", + "api": "requests", + "name": "RestartMedia", + "category": "media control", + "since": "unreleased", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "RestartMedia" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "RestartMedia" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Stop a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)", + "param": "{String} `sourceName` Source name.", + "api": "requests", + "name": "StopMedia", + "category": "media control", + "since": "unreleased", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "StopMedia" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "StopMedia" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Skip to the next media item in the playlist. Supports only vlc media source (as of OBS v25.0.8)", + "param": "{String} `sourceName` Source name.", + "api": "requests", + "name": "NextMedia", + "category": "media control", + "since": "unreleased", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "NextMedia" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "NextMedia" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Go to the previous media item in the playlist. Supports only vlc media source (as of OBS v25.0.8)", + "param": "{String} `sourceName` Source name.", + "api": "requests", + "name": "PreviousMedia", + "category": "media control", + "since": "unreleased", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "PreviousMedia" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "PreviousMedia" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the length of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)\nNote: For some reason, for the first 5 or so seconds that the media is playing, the total duration can be off by upwards of 50ms.", + "param": "{String} `sourceName` Source name.", + "return": "{int} `mediaDuration` The total length of media in milliseconds..", + "api": "requests", + "name": "GetMediaDuration", + "category": "media control", + "since": "unreleased", + "returns": [ + { + "type": "int", + "name": "mediaDuration", + "description": "The total length of media in milliseconds.." + } + ], + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "GetMediaDuration" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetMediaDuration" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the current timestamp of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)", + "param": "{String} `sourceName` Source name.", + "return": "{int} `timestamp` The time in milliseconds since the start of the media.", + "api": "requests", + "name": "GetMediaTime", + "category": "media control", + "since": "unreleased", + "returns": [ + { + "type": "int", + "name": "timestamp", + "description": "The time in milliseconds since the start of the media." + } + ], + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "GetMediaTime" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetMediaTime" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Set the timestamp of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)", + "param": [ + "{String} `sourceName` Source name.", + "{int} `timestamp` Milliseconds to set the timestamp to." + ], + "api": "requests", + "name": "SetMediaTime", + "category": "media control", + "since": "unreleased", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + }, + { + "type": "int", + "name": "timestamp", + "description": "Milliseconds to set the timestamp to." + } + ], + "names": [ + { + "name": "", + "description": "SetMediaTime" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "SetMediaTime" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Scrub media using a supplied offset. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)\nNote: Due to processing/network delays, this request is not perfect. The processing rate of this request has also not been tested.", + "param": [ + "{String} `sourceName` Source name.", + "{int} `timeOffset` Millisecond offset (positive or negative) to offset the current media position." + ], + "api": "requests", + "name": "ScrubMedia", + "category": "media control", + "since": "unreleased", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + }, + { + "type": "int", + "name": "timeOffset", + "description": "Millisecond offset (positive or negative) to offset the current media position." + } + ], + "names": [ + { + "name": "", + "description": "ScrubMedia" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "ScrubMedia" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the current playing state of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)", + "param": "{String} `sourceName` Source name.", + "return": "{String} `mediaState` The media state of the provided source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown`", + "api": "requests", + "name": "GetMediaState", + "category": "media control", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "mediaState", + "description": "The media state of the provided source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown`" + } + ], + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "GetMediaState" + } + ], + "categories": [ + { + "name": "", + "description": "media control" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetMediaState" }, "lead": "", "type": "class", @@ -5464,13 +4642,74 @@ } ], "sources": [ + { + "subheads": [], + "description": "List the media state of all media sources (vlc and media source)", + "return": [ + "{Array} `mediaSources` Array of sources", + "{String} `mediaSources.*.sourceName` Unique source name", + "{String} `mediaSources.*.sourceKind` Unique source internal type (a.k.a `ffmpeg_source` or `vlc_source`)", + "{String} `mediaSources.*.mediaState` The current state of media for that source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown`" + ], + "api": "requests", + "name": "GetMediaSourcesList", + "category": "sources", + "since": "unreleased", + "returns": [ + { + "type": "Array", + "name": "mediaSources", + "description": "Array of sources" + }, + { + "type": "String", + "name": "mediaSources.*.sourceName", + "description": "Unique source name" + }, + { + "type": "String", + "name": "mediaSources.*.sourceKind", + "description": "Unique source internal type (a.k.a `ffmpeg_source` or `vlc_source`)" + }, + { + "type": "String", + "name": "mediaSources.*.mediaState", + "description": "The current state of media for that source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown`" + } + ], + "names": [ + { + "name": "", + "description": "GetMediaSourcesList" + } + ], + "categories": [ + { + "name": "", + "description": "sources" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetMediaSourcesList" + }, + "lead": "", + "type": "class", + "examples": [] + }, { "subheads": [], "description": "List all sources available in the running OBS instance", "return": [ "{Array} `sources` Array of sources", "{String} `sources.*.name` Unique source name", - "{String} `sources.*.typeId` Non-unique source internal type (a.k.a type id)", + "{String} `sources.*.typeId` Non-unique source internal type (a.k.a kind)", "{String} `sources.*.type` Source type. Value is one of the following: \"input\", \"filter\", \"transition\", \"scene\" or \"unknown\"" ], "api": "requests", @@ -5491,7 +4730,7 @@ { "type": "String", "name": "sources.*.typeId", - "description": "Non-unique source internal type (a.k.a type id)" + "description": "Non-unique source internal type (a.k.a kind)" }, { "type": "String", @@ -5642,11 +4881,14 @@ }, { "subheads": [], - "description": "Get the volume of the specified source.", - "param": "{String} `source` Source name.", + "description": "Get the volume of the specified source. Default response uses mul format, NOT SLIDER PERCENTAGE.", + "param": [ + "{String} `source` Source name.", + "{boolean (optional)} `useDecibel` Output volume in decibels of attenuation instead of amplitude/mul." + ], "return": [ "{String} `name` Source name.", - "{double} `volume` Volume of the source. Between `0.0` and `1.0`.", + "{double} `volume` Volume of the source. Between `0.0` and `1.0` if using mul, under `0.0` if using dB (since it is attenuating).", "{boolean} `muted` Indicates whether the source is muted." ], "api": "requests", @@ -5662,7 +4904,7 @@ { "type": "double", "name": "volume", - "description": "Volume of the source. Between `0.0` and `1.0`." + "description": "Volume of the source. Between `0.0` and `1.0` if using mul, under `0.0` if using dB (since it is attenuating)." }, { "type": "boolean", @@ -5675,6 +4917,11 @@ "type": "String", "name": "source", "description": "Source name." + }, + { + "type": "boolean (optional)", + "name": "useDecibel", + "description": "Output volume in decibels of attenuation instead of amplitude/mul." } ], "names": [ @@ -5705,10 +4952,11 @@ }, { "subheads": [], - "description": "Set the volume of the specified source.", + "description": "Set the volume of the specified source. Default request format uses mul, NOT SLIDER PERCENTAGE.", "param": [ "{String} `source` Source name.", - "{double} `volume` Desired volume. Must be between `0.0` and `1.0`." + "{double} `volume` Desired volume. Must be between `0.0` and `1.0` for mul, and under 0.0 for dB. Note: OBS will interpret dB values under -100.0 as Inf.", + "{boolean (optional)} `useDecibel` Interperet `volume` data as decibels instead of amplitude/mul." ], "api": "requests", "name": "SetVolume", @@ -5723,7 +4971,12 @@ { "type": "double", "name": "volume", - "description": "Desired volume. Must be between `0.0` and `1.0`." + "description": "Desired volume. Must be between `0.0` and `1.0` for mul, and under 0.0 for dB. Note: OBS will interpret dB values under -100.0 as Inf." + }, + { + "type": "boolean (optional)", + "name": "useDecibel", + "description": "Interperet `volume` data as decibels instead of amplitude/mul." } ], "names": [ @@ -5899,6 +5152,104 @@ "type": "class", "examples": [] }, + { + "subheads": [], + "description": "Get the audio's active status of a specified source.", + "param": "{String} `sourceName` Source name.", + "return": "{boolean} `audioActive` Audio active status of the source.", + "api": "requests", + "name": "GetAudioActive", + "category": "sources", + "since": "unreleased", + "returns": [ + { + "type": "boolean", + "name": "audioActive", + "description": "Audio active status of the source." + } + ], + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "GetAudioActive" + } + ], + "categories": [ + { + "name": "", + "description": "sources" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetAudioActive" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: If the new name already exists as a source, obs-websocket will return an error.", + "param": [ + "{String} `sourceName` Source name.", + "{String} `newName` New source name." + ], + "api": "requests", + "name": "SetSourceName", + "category": "sources", + "since": "4.8.0", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + }, + { + "type": "String", + "name": "newName", + "description": "New source name." + } + ], + "names": [ + { + "name": "", + "description": "SetSourceName" + } + ], + "categories": [ + { + "name": "", + "description": "sources" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "SetSourceName" + }, + "lead": "Sets (aka rename) the name of a source. Also works with scenes since scenes are technically sources in OBS.", + "type": "class", + "examples": [] + }, { "subheads": [], "description": "Set the audio sync offset of a specified source.", @@ -6160,8 +5511,8 @@ "return": [ "{String} `source` Source name.", "{String} `align` Text Alignment (\"left\", \"center\", \"right\").", - "{int} `bk-color` Background color.", - "{int} `bk-opacity` Background opacity (0-100).", + "{int} `bk_color` Background color.", + "{int} `bk_opacity` Background opacity (0-100).", "{boolean} `chatlog` Chat log.", "{int} `chatlog_lines` Chat log lines.", "{int} `color` Text color.", @@ -6204,12 +5555,12 @@ }, { "type": "int", - "name": "bk-color", + "name": "bk_color", "description": "Background color." }, { "type": "int", - "name": "bk-opacity", + "name": "bk_opacity", "description": "Background opacity (0-100)." }, { @@ -6372,8 +5723,8 @@ "param": [ "{String} `source` Name of the source.", "{String (optional)} `align` Text Alignment (\"left\", \"center\", \"right\").", - "{int (optional)} `bk-color` Background color.", - "{int (optional)} `bk-opacity` Background opacity (0-100).", + "{int (optional)} `bk_color` Background color.", + "{int (optional)} `bk_opacity` Background opacity (0-100).", "{boolean (optional)} `chatlog` Chat log.", "{int (optional)} `chatlog_lines` Chat log lines.", "{int (optional)} `color` Text color.", @@ -6417,12 +5768,12 @@ }, { "type": "int (optional)", - "name": "bk-color", + "name": "bk_color", "description": "Background color." }, { "type": "int (optional)", - "name": "bk-opacity", + "name": "bk_opacity", "description": "Background opacity (0-100)." }, { @@ -6870,7 +6221,7 @@ "name": "GetBrowserSourceProperties", "category": "sources", "since": "4.1.0", - "deprecated": "Since 4.8.0. Prefer the use of GetSourceSettings.", + "deprecated": "Since 4.8.0. Prefer the use of GetSourceSettings. Will be removed in v5.0.0", "returns": [ { "type": "String", @@ -6946,7 +6297,7 @@ "deprecateds": [ { "name": "", - "description": "Since 4.8.0. Prefer the use of GetSourceSettings." + "description": "Since 4.8.0. Prefer the use of GetSourceSettings. Will be removed in v5.0.0" } ], "heading": { @@ -6975,7 +6326,7 @@ "api": "requests", "name": "SetBrowserSourceProperties", "category": "sources", - "deprecated": "Since 4.8.0. Prefer the use of SetSourceSettings.", + "deprecated": "Since 4.8.0. Prefer the use of SetSourceSettings. Will be removed in v5.0.0", "since": "4.1.0", "params": [ { @@ -7044,7 +6395,7 @@ "deprecateds": [ { "name": "", - "description": "Since 4.8.0. Prefer the use of SetSourceSettings." + "description": "Since 4.8.0. Prefer the use of SetSourceSettings. Will be removed in v5.0.0" } ], "sinces": [ @@ -7610,13 +6961,113 @@ "type": "class", "examples": [] }, + { + "subheads": [], + "description": "Get the audio monitoring type of the specified source.", + "param": "{String} `sourceName` Source name.", + "return": "{String} `monitorType` The monitor type in use. Options: `none`, `monitorOnly`, `monitorAndOutput`.", + "api": "requests", + "name": "GetAudioMonitorType", + "category": "sources", + "since": "4.8.0", + "returns": [ + { + "type": "String", + "name": "monitorType", + "description": "The monitor type in use. Options: `none`, `monitorOnly`, `monitorAndOutput`." + } + ], + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + } + ], + "names": [ + { + "name": "", + "description": "GetAudioMonitorType" + } + ], + "categories": [ + { + "name": "", + "description": "sources" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "GetAudioMonitorType" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Set the audio monitoring type of the specified source.", + "param": [ + "{String} `sourceName` Source name.", + "{String} `monitorType` The monitor type to use. Options: `none`, `monitorOnly`, `monitorAndOutput`." + ], + "api": "requests", + "name": "SetAudioMonitorType", + "category": "sources", + "since": "4.8.0", + "params": [ + { + "type": "String", + "name": "sourceName", + "description": "Source name." + }, + { + "type": "String", + "name": "monitorType", + "description": "The monitor type to use. Options: `none`, `monitorOnly`, `monitorAndOutput`." + } + ], + "names": [ + { + "name": "", + "description": "SetAudioMonitorType" + } + ], + "categories": [ + { + "name": "", + "description": "sources" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "SetAudioMonitorType" + }, + "lead": "", + "type": "class", + "examples": [] + }, { "subheads": [], "description": "\n\nAt least `embedPictureFormat` or `saveToFilePath` must be specified.\n\nClients can specify `width` and `height` parameters to receive scaled pictures. Aspect ratio is\npreserved if only one of these two parameters is specified.", "param": [ - "{String} `sourceName` Source name. Note that, since scenes are also sources, you can also provide a scene name.", + "{String (optional)} `sourceName` Source name. Note that, since scenes are also sources, you can also provide a scene name. If not provided, the currently active scene is used.", "{String (optional)} `embedPictureFormat` Format of the Data URI encoded picture. Can be \"png\", \"jpg\", \"jpeg\" or \"bmp\" (or any other value supported by Qt's Image module)", "{String (optional)} `saveToFilePath` Full file path (file extension included) where the captured image is to be saved. Can be in a format different from `pictureFormat`. Can be a relative path.", + "{String (optional)} `fileFormat` Format to save the image file as (one of the values provided in the `supported-image-export-formats` response field of `GetVersion`). If not specified, tries to guess based on file extension.", + "{int (optional)} `compressionQuality` Compression ratio between -1 and 100 to write the image with. -1 is automatic, 1 is smallest file/most compression, 100 is largest file/least compression. Varies with image type.", "{int (optional)} `width` Screenshot width. Defaults to the source's base width.", "{int (optional)} `height` Screenshot height. Defaults to the source's base height." ], @@ -7648,9 +7099,9 @@ ], "params": [ { - "type": "String", + "type": "String (optional)", "name": "sourceName", - "description": "Source name. Note that, since scenes are also sources, you can also provide a scene name." + "description": "Source name. Note that, since scenes are also sources, you can also provide a scene name. If not provided, the currently active scene is used." }, { "type": "String (optional)", @@ -7662,6 +7113,16 @@ "name": "saveToFilePath", "description": "Full file path (file extension included) where the captured image is to be saved. Can be in a format different from `pictureFormat`. Can be a relative path." }, + { + "type": "String (optional)", + "name": "fileFormat", + "description": "Format to save the image file as (one of the values provided in the `supported-image-export-formats` response field of `GetVersion`). If not specified, tries to guess based on file extension." + }, + { + "type": "int (optional)", + "name": "compressionQuality", + "description": "Compression ratio between -1 and 100 to write the image with. -1 is automatic, 1 is smallest file/most compression, 100 is largest file/least compression. Varies with image type." + }, { "type": "int (optional)", "name": "width", @@ -7700,6 +7161,2347 @@ "examples": [] } ], + "outputs": [ + { + "subheads": [], + "description": "List existing outputs", + "return": "{Array} `outputs` Outputs list", + "api": "requests", + "name": "ListOutputs", + "category": "outputs", + "since": "4.7.0", + "returns": [ + { + "type": "Array", + "name": "outputs", + "description": "Outputs list" + } + ], + "names": [ + { + "name": "", + "description": "ListOutputs" + } + ], + "categories": [ + { + "name": "", + "description": "outputs" + } + ], + "sinces": [ + { + "name": "", + "description": "4.7.0" + } + ], + "heading": { + "level": 2, + "text": "ListOutputs" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get information about a single output", + "param": "{String} `outputName` Output name", + "return": "{Output} `outputInfo` Output info", + "api": "requests", + "name": "GetOutputInfo", + "category": "outputs", + "since": "4.7.0", + "returns": [ + { + "type": "Output", + "name": "outputInfo", + "description": "Output info" + } + ], + "params": [ + { + "type": "String", + "name": "outputName", + "description": "Output name" + } + ], + "names": [ + { + "name": "", + "description": "GetOutputInfo" + } + ], + "categories": [ + { + "name": "", + "description": "outputs" + } + ], + "sinces": [ + { + "name": "", + "description": "4.7.0" + } + ], + "heading": { + "level": 2, + "text": "GetOutputInfo" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: Controlling outputs is an experimental feature of obs-websocket. Some plugins which add outputs to OBS may not function properly when they are controlled in this way.", + "param": "{String} `outputName` Output name", + "api": "requests", + "name": "StartOutput", + "category": "outputs", + "since": "4.7.0", + "params": [ + { + "type": "String", + "name": "outputName", + "description": "Output name" + } + ], + "names": [ + { + "name": "", + "description": "StartOutput" + } + ], + "categories": [ + { + "name": "", + "description": "outputs" + } + ], + "sinces": [ + { + "name": "", + "description": "4.7.0" + } + ], + "heading": { + "level": 2, + "text": "StartOutput" + }, + "lead": "Start an output", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nNote: Controlling outputs is an experimental feature of obs-websocket. Some plugins which add outputs to OBS may not function properly when they are controlled in this way.", + "param": [ + "{String} `outputName` Output name", + "{boolean (optional)} `force` Force stop (default: false)" + ], + "api": "requests", + "name": "StopOutput", + "category": "outputs", + "since": "4.7.0", + "params": [ + { + "type": "String", + "name": "outputName", + "description": "Output name" + }, + { + "type": "boolean (optional)", + "name": "force", + "description": "Force stop (default: false)" + } + ], + "names": [ + { + "name": "", + "description": "StopOutput" + } + ], + "categories": [ + { + "name": "", + "description": "outputs" + } + ], + "sinces": [ + { + "name": "", + "description": "4.7.0" + } + ], + "heading": { + "level": 2, + "text": "StopOutput" + }, + "lead": "Stop an output", + "type": "class", + "examples": [] + } + ], + "profiles": [ + { + "subheads": [], + "description": "Set the currently active profile.", + "param": "{String} `profile-name` Name of the desired profile.", + "api": "requests", + "name": "SetCurrentProfile", + "category": "profiles", + "since": "4.0.0", + "params": [ + { + "type": "String", + "name": "profile-name", + "description": "Name of the desired profile." + } + ], + "names": [ + { + "name": "", + "description": "SetCurrentProfile" + } + ], + "categories": [ + { + "name": "", + "description": "profiles" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "heading": { + "level": 2, + "text": "SetCurrentProfile" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the name of the current profile.", + "return": "{String} `profile-name` Name of the currently active profile.", + "api": "requests", + "name": "GetCurrentProfile", + "category": "profiles", + "since": "4.0.0", + "returns": [ + { + "type": "String", + "name": "profile-name", + "description": "Name of the currently active profile." + } + ], + "names": [ + { + "name": "", + "description": "GetCurrentProfile" + } + ], + "categories": [ + { + "name": "", + "description": "profiles" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "heading": { + "level": 2, + "text": "GetCurrentProfile" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get a list of available profiles.", + "return": [ + "{Array} `profiles` List of available profiles.", + "{String} `profiles.*.profile-name` Filter name" + ], + "api": "requests", + "name": "ListProfiles", + "category": "profiles", + "since": "4.0.0", + "returns": [ + { + "type": "Array", + "name": "profiles", + "description": "List of available profiles." + }, + { + "type": "String", + "name": "profiles.*.profile-name", + "description": "Filter name" + } + ], + "names": [ + { + "name": "", + "description": "ListProfiles" + } + ], + "categories": [ + { + "name": "", + "description": "profiles" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "heading": { + "level": 2, + "text": "ListProfiles" + }, + "lead": "", + "type": "class", + "examples": [] + } + ], + "recording": [ + { + "subheads": [], + "description": "Get current recording status.", + "return": [ + "{boolean} `isRecording` Current recording status.", + "{boolean} `isRecordingPaused` Whether the recording is paused or not.", + "{String (optional)} `recordTimecode` Time elapsed since recording started (only present if currently recording)." + ], + "api": "requests", + "name": "GetRecordingStatus", + "category": "recording", + "since": "unreleased", + "returns": [ + { + "type": "boolean", + "name": "isRecording", + "description": "Current recording status." + }, + { + "type": "boolean", + "name": "isRecordingPaused", + "description": "Whether the recording is paused or not." + }, + { + "type": "String (optional)", + "name": "recordTimecode", + "description": "Time elapsed since recording started (only present if currently recording)." + } + ], + "names": [ + { + "name": "", + "description": "GetRecordingStatus" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetRecordingStatus" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Toggle recording on or off (depending on the current recording state).", + "api": "requests", + "name": "StartStopRecording", + "category": "recording", + "since": "0.3", + "names": [ + { + "name": "", + "description": "StartStopRecording" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "0.3" + } + ], + "heading": { + "level": 2, + "text": "StartStopRecording" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Start recording.\nWill return an `error` if recording is already active.", + "api": "requests", + "name": "StartRecording", + "category": "recording", + "since": "4.1.0", + "names": [ + { + "name": "", + "description": "StartRecording" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "4.1.0" + } + ], + "heading": { + "level": 2, + "text": "StartRecording" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Stop recording.\nWill return an `error` if recording is not active.", + "api": "requests", + "name": "StopRecording", + "category": "recording", + "since": "4.1.0", + "names": [ + { + "name": "", + "description": "StopRecording" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "4.1.0" + } + ], + "heading": { + "level": 2, + "text": "StopRecording" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Pause the current recording.\nReturns an error if recording is not active or already paused.", + "api": "requests", + "name": "PauseRecording", + "category": "recording", + "since": "4.7.0", + "names": [ + { + "name": "", + "description": "PauseRecording" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "4.7.0" + } + ], + "heading": { + "level": 2, + "text": "PauseRecording" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Resume/unpause the current recording (if paused).\nReturns an error if recording is not active or not paused.", + "api": "requests", + "name": "ResumeRecording", + "category": "recording", + "since": "4.7.0", + "names": [ + { + "name": "", + "description": "ResumeRecording" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "4.7.0" + } + ], + "heading": { + "level": 2, + "text": "ResumeRecording" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "\n\nPlease note: if `SetRecordingFolder` is called while a recording is\nin progress, the change won't be applied immediately and will be\neffective on the next recording.", + "param": "{String} `rec-folder` Path of the recording folder.", + "api": "requests", + "name": "SetRecordingFolder", + "category": "recording", + "since": "4.1.0", + "params": [ + { + "type": "String", + "name": "rec-folder", + "description": "Path of the recording folder." + } + ], + "names": [ + { + "name": "", + "description": "SetRecordingFolder" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "4.1.0" + } + ], + "heading": { + "level": 2, + "text": "SetRecordingFolder" + }, + "lead": "In the current profile, sets the recording folder of the Simple and Advanced output modes to the specified value.", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the path of the current recording folder.", + "return": "{String} `rec-folder` Path of the recording folder.", + "api": "requests", + "name": "GetRecordingFolder", + "category": "recording", + "since": "4.1.0", + "returns": [ + { + "type": "String", + "name": "rec-folder", + "description": "Path of the recording folder." + } + ], + "names": [ + { + "name": "", + "description": "GetRecordingFolder" + } + ], + "categories": [ + { + "name": "", + "description": "recording" + } + ], + "sinces": [ + { + "name": "", + "description": "4.1.0" + } + ], + "heading": { + "level": 2, + "text": "GetRecordingFolder" + }, + "lead": "", + "type": "class", + "examples": [] + } + ], + "replay buffer": [ + { + "subheads": [], + "description": "Get the status of the OBS replay buffer.", + "return": "{boolean} `isReplayBufferActive` Current recording status.", + "api": "requests", + "name": "GetReplayBufferStatus", + "category": "replay buffer", + "since": "unreleased", + "returns": [ + { + "type": "boolean", + "name": "isReplayBufferActive", + "description": "Current recording status." + } + ], + "names": [ + { + "name": "", + "description": "GetReplayBufferStatus" + } + ], + "categories": [ + { + "name": "", + "description": "replay buffer" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetReplayBufferStatus" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Toggle the Replay Buffer on/off (depending on the current state of the replay buffer).", + "api": "requests", + "name": "StartStopReplayBuffer", + "category": "replay buffer", + "since": "4.2.0", + "names": [ + { + "name": "", + "description": "StartStopReplayBuffer" + } + ], + "categories": [ + { + "name": "", + "description": "replay buffer" + } + ], + "sinces": [ + { + "name": "", + "description": "4.2.0" + } + ], + "heading": { + "level": 2, + "text": "StartStopReplayBuffer" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Start recording into the Replay Buffer.\nWill return an `error` if the Replay Buffer is already active or if the\n\"Save Replay Buffer\" hotkey is not set in OBS' settings.\nSetting this hotkey is mandatory, even when triggering saves only\nthrough obs-websocket.", + "api": "requests", + "name": "StartReplayBuffer", + "category": "replay buffer", + "since": "4.2.0", + "names": [ + { + "name": "", + "description": "StartReplayBuffer" + } + ], + "categories": [ + { + "name": "", + "description": "replay buffer" + } + ], + "sinces": [ + { + "name": "", + "description": "4.2.0" + } + ], + "heading": { + "level": 2, + "text": "StartReplayBuffer" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Stop recording into the Replay Buffer.\nWill return an `error` if the Replay Buffer is not active.", + "api": "requests", + "name": "StopReplayBuffer", + "category": "replay buffer", + "since": "4.2.0", + "names": [ + { + "name": "", + "description": "StopReplayBuffer" + } + ], + "categories": [ + { + "name": "", + "description": "replay buffer" + } + ], + "sinces": [ + { + "name": "", + "description": "4.2.0" + } + ], + "heading": { + "level": 2, + "text": "StopReplayBuffer" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Flush and save the contents of the Replay Buffer to disk. This is\nbasically the same as triggering the \"Save Replay Buffer\" hotkey.\nWill return an `error` if the Replay Buffer is not active.", + "api": "requests", + "name": "SaveReplayBuffer", + "category": "replay buffer", + "since": "4.2.0", + "names": [ + { + "name": "", + "description": "SaveReplayBuffer" + } + ], + "categories": [ + { + "name": "", + "description": "replay buffer" + } + ], + "sinces": [ + { + "name": "", + "description": "4.2.0" + } + ], + "heading": { + "level": 2, + "text": "SaveReplayBuffer" + }, + "lead": "", + "type": "class", + "examples": [] + } + ], + "scene collections": [ + { + "subheads": [], + "description": "Change the active scene collection.", + "param": "{String} `sc-name` Name of the desired scene collection.", + "api": "requests", + "name": "SetCurrentSceneCollection", + "category": "scene collections", + "since": "4.0.0", + "params": [ + { + "type": "String", + "name": "sc-name", + "description": "Name of the desired scene collection." + } + ], + "names": [ + { + "name": "", + "description": "SetCurrentSceneCollection" + } + ], + "categories": [ + { + "name": "", + "description": "scene collections" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "heading": { + "level": 2, + "text": "SetCurrentSceneCollection" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the name of the current scene collection.", + "return": "{String} `sc-name` Name of the currently active scene collection.", + "api": "requests", + "name": "GetCurrentSceneCollection", + "category": "scene collections", + "since": "4.0.0", + "returns": [ + { + "type": "String", + "name": "sc-name", + "description": "Name of the currently active scene collection." + } + ], + "names": [ + { + "name": "", + "description": "GetCurrentSceneCollection" + } + ], + "categories": [ + { + "name": "", + "description": "scene collections" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "heading": { + "level": 2, + "text": "GetCurrentSceneCollection" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "List available scene collections", + "return": [ + "{Array} `scene-collections` Scene collections list", + "{String} `scene-collections.*.sc-name` Scene collection name" + ], + "api": "requests", + "name": "ListSceneCollections", + "category": "scene collections", + "since": "4.0.0", + "returns": [ + { + "type": "Array", + "name": "scene-collections", + "description": "Scene collections list" + }, + { + "type": "String", + "name": "scene-collections.*.sc-name", + "description": "Scene collection name" + } + ], + "names": [ + { + "name": "", + "description": "ListSceneCollections" + } + ], + "categories": [ + { + "name": "", + "description": "scene collections" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "heading": { + "level": 2, + "text": "ListSceneCollections" + }, + "lead": "", + "type": "class", + "examples": [] + } + ], + "scene items": [ + { + "subheads": [], + "description": "Get a list of all scene items in a scene.", + "param": "{String (optional)} `sceneName` Name of the scene to get the list of scene items from. Defaults to the current scene if not specified.", + "return": [ + "{String} `sceneName` Name of the requested (or current) scene", + "{Array} `sceneItems` Array of scene items", + "{int} `sceneItems.*.itemId` Unique item id of the source item", + "{String} `sceneItems.*.sourceKind` ID if the scene item's source. For example `vlc_source` or `image_source`", + "{String} `sceneItems.*.sourceName` Name of the scene item's source", + "{String} `sceneItems.*.sourceType` Type of the scene item's source. Either `input`, `group`, or `scene`" + ], + "api": "requests", + "name": "GetSceneItemList", + "category": "scene items", + "since": "unreleased", + "returns": [ + { + "type": "String", + "name": "sceneName", + "description": "Name of the requested (or current) scene" + }, + { + "type": "Array", + "name": "sceneItems", + "description": "Array of scene items" + }, + { + "type": "int", + "name": "sceneItems.*.itemId", + "description": "Unique item id of the source item" + }, + { + "type": "String", + "name": "sceneItems.*.sourceKind", + "description": "ID if the scene item's source. For example `vlc_source` or `image_source`" + }, + { + "type": "String", + "name": "sceneItems.*.sourceName", + "description": "Name of the scene item's source" + }, + { + "type": "String", + "name": "sceneItems.*.sourceType", + "description": "Type of the scene item's source. Either `input`, `group`, or `scene`" + } + ], + "params": [ + { + "type": "String (optional)", + "name": "sceneName", + "description": "Name of the scene to get the list of scene items from. Defaults to the current scene if not specified." + } + ], + "names": [ + { + "name": "", + "description": "GetSceneItemList" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetSceneItemList" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Gets the scene specific properties of the specified source item.\nCoordinates are relative to the item's parent (the scene or group it belongs to).", + "param": [ + "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", + "{String | Object} `item` Scene Item name (if this field is a string) or specification (if it is an object).", + "{String (optional)} `item.name` Scene Item name (if the `item` field is an object)", + "{int (optional)} `item.id` Scene Item ID (if the `item` field is an object)" + ], + "return": [ + "{String} `name` Scene Item name.", + "{int} `itemId` Scene Item ID.", + "{double} `position.x` The x position of the source from the left.", + "{double} `position.y` The y position of the source from the top.", + "{int} `position.alignment` The point on the source that the item is manipulated from.", + "{double} `rotation` The clockwise rotation of the item in degrees around the point of alignment.", + "{double} `scale.x` The x-scale factor of the source.", + "{double} `scale.y` The y-scale factor of the source.", + "{int} `crop.top` The number of pixels cropped off the top of the source before scaling.", + "{int} `crop.right` The number of pixels cropped off the right of the source before scaling.", + "{int} `crop.bottom` The number of pixels cropped off the bottom of the source before scaling.", + "{int} `crop.left` The number of pixels cropped off the left of the source before scaling.", + "{bool} `visible` If the source is visible.", + "{bool} `muted` If the source is muted.", + "{bool} `locked` If the source's transform is locked.", + "{String} `bounds.type` Type of bounding box. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\".", + "{int} `bounds.alignment` Alignment of the bounding box.", + "{double} `bounds.x` Width of the bounding box.", + "{double} `bounds.y` Height of the bounding box.", + "{int} `sourceWidth` Base width (without scaling) of the source", + "{int} `sourceHeight` Base source (without scaling) of the source", + "{double} `width` Scene item width (base source width multiplied by the horizontal scaling factor)", + "{double} `height` Scene item height (base source height multiplied by the vertical scaling factor)", + "{int} `alignment` The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis.", + "{String (optional)} `parentGroupName` Name of the item's parent (if this item belongs to a group)", + "{Array (optional)} `groupChildren` List of children (if this item is a group)" + ], + "api": "requests", + "name": "GetSceneItemProperties", + "category": "scene items", + "since": "4.3.0", + "returns": [ + { + "type": "String", + "name": "name", + "description": "Scene Item name." + }, + { + "type": "int", + "name": "itemId", + "description": "Scene Item ID." + }, + { + "type": "double", + "name": "position.x", + "description": "The x position of the source from the left." + }, + { + "type": "double", + "name": "position.y", + "description": "The y position of the source from the top." + }, + { + "type": "int", + "name": "position.alignment", + "description": "The point on the source that the item is manipulated from." + }, + { + "type": "double", + "name": "rotation", + "description": "The clockwise rotation of the item in degrees around the point of alignment." + }, + { + "type": "double", + "name": "scale.x", + "description": "The x-scale factor of the source." + }, + { + "type": "double", + "name": "scale.y", + "description": "The y-scale factor of the source." + }, + { + "type": "int", + "name": "crop.top", + "description": "The number of pixels cropped off the top of the source before scaling." + }, + { + "type": "int", + "name": "crop.right", + "description": "The number of pixels cropped off the right of the source before scaling." + }, + { + "type": "int", + "name": "crop.bottom", + "description": "The number of pixels cropped off the bottom of the source before scaling." + }, + { + "type": "int", + "name": "crop.left", + "description": "The number of pixels cropped off the left of the source before scaling." + }, + { + "type": "bool", + "name": "visible", + "description": "If the source is visible." + }, + { + "type": "bool", + "name": "muted", + "description": "If the source is muted." + }, + { + "type": "bool", + "name": "locked", + "description": "If the source's transform is locked." + }, + { + "type": "String", + "name": "bounds.type", + "description": "Type of bounding box. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\"." + }, + { + "type": "int", + "name": "bounds.alignment", + "description": "Alignment of the bounding box." + }, + { + "type": "double", + "name": "bounds.x", + "description": "Width of the bounding box." + }, + { + "type": "double", + "name": "bounds.y", + "description": "Height of the bounding box." + }, + { + "type": "int", + "name": "sourceWidth", + "description": "Base width (without scaling) of the source" + }, + { + "type": "int", + "name": "sourceHeight", + "description": "Base source (without scaling) of the source" + }, + { + "type": "double", + "name": "width", + "description": "Scene item width (base source width multiplied by the horizontal scaling factor)" + }, + { + "type": "double", + "name": "height", + "description": "Scene item height (base source height multiplied by the vertical scaling factor)" + }, + { + "type": "int", + "name": "alignment", + "description": "The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis." + }, + { + "type": "String (optional)", + "name": "parentGroupName", + "description": "Name of the item's parent (if this item belongs to a group)" + }, + { + "type": "Array (optional)", + "name": "groupChildren", + "description": "List of children (if this item is a group)" + } + ], + "params": [ + { + "type": "String (optional)", + "name": "scene-name", + "description": "Name of the scene the scene item belongs to. Defaults to the current scene." + }, + { + "type": "String | Object", + "name": "item", + "description": "Scene Item name (if this field is a string) or specification (if it is an object)." + }, + { + "type": "String (optional)", + "name": "item.name", + "description": "Scene Item name (if the `item` field is an object)" + }, + { + "type": "int (optional)", + "name": "item.id", + "description": "Scene Item ID (if the `item` field is an object)" + } + ], + "names": [ + { + "name": "", + "description": "GetSceneItemProperties" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.3.0" + } + ], + "heading": { + "level": 2, + "text": "GetSceneItemProperties" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Sets the scene specific properties of a source. Unspecified properties will remain unchanged.\nCoordinates are relative to the item's parent (the scene or group it belongs to).", + "param": [ + "{String (optional)} `scene-name` Name of the scene the source item belongs to. Defaults to the current scene.", + "{String | Object} `item` Scene Item name (if this field is a string) or specification (if it is an object).", + "{String (optional)} `item.name` Scene Item name (if the `item` field is an object)", + "{int (optional)} `item.id` Scene Item ID (if the `item` field is an object)", + "{double (optional)} `position.x` The new x position of the source.", + "{double (optional)} `position.y` The new y position of the source.", + "{int (optional)} `position.alignment` The new alignment of the source.", + "{double (optional)} `rotation` The new clockwise rotation of the item in degrees.", + "{double (optional)} `scale.x` The new x scale of the item.", + "{double (optional)} `scale.y` The new y scale of the item.", + "{int (optional)} `crop.top` The new amount of pixels cropped off the top of the source before scaling.", + "{int (optional)} `crop.bottom` The new amount of pixels cropped off the bottom of the source before scaling.", + "{int (optional)} `crop.left` The new amount of pixels cropped off the left of the source before scaling.", + "{int (optional)} `crop.right` The new amount of pixels cropped off the right of the source before scaling.", + "{bool (optional)} `visible` The new visibility of the source. 'true' shows source, 'false' hides source.", + "{bool (optional)} `locked` The new locked status of the source. 'true' keeps it in its current position, 'false' allows movement.", + "{String (optional)} `bounds.type` The new bounds type of the source. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\".", + "{int (optional)} `bounds.alignment` The new alignment of the bounding box. (0-2, 4-6, 8-10)", + "{double (optional)} `bounds.x` The new width of the bounding box.", + "{double (optional)} `bounds.y` The new height of the bounding box." + ], + "api": "requests", + "name": "SetSceneItemProperties", + "category": "scene items", + "since": "4.3.0", + "params": [ + { + "type": "String (optional)", + "name": "scene-name", + "description": "Name of the scene the source item belongs to. Defaults to the current scene." + }, + { + "type": "String | Object", + "name": "item", + "description": "Scene Item name (if this field is a string) or specification (if it is an object)." + }, + { + "type": "String (optional)", + "name": "item.name", + "description": "Scene Item name (if the `item` field is an object)" + }, + { + "type": "int (optional)", + "name": "item.id", + "description": "Scene Item ID (if the `item` field is an object)" + }, + { + "type": "double (optional)", + "name": "position.x", + "description": "The new x position of the source." + }, + { + "type": "double (optional)", + "name": "position.y", + "description": "The new y position of the source." + }, + { + "type": "int (optional)", + "name": "position.alignment", + "description": "The new alignment of the source." + }, + { + "type": "double (optional)", + "name": "rotation", + "description": "The new clockwise rotation of the item in degrees." + }, + { + "type": "double (optional)", + "name": "scale.x", + "description": "The new x scale of the item." + }, + { + "type": "double (optional)", + "name": "scale.y", + "description": "The new y scale of the item." + }, + { + "type": "int (optional)", + "name": "crop.top", + "description": "The new amount of pixels cropped off the top of the source before scaling." + }, + { + "type": "int (optional)", + "name": "crop.bottom", + "description": "The new amount of pixels cropped off the bottom of the source before scaling." + }, + { + "type": "int (optional)", + "name": "crop.left", + "description": "The new amount of pixels cropped off the left of the source before scaling." + }, + { + "type": "int (optional)", + "name": "crop.right", + "description": "The new amount of pixels cropped off the right of the source before scaling." + }, + { + "type": "bool (optional)", + "name": "visible", + "description": "The new visibility of the source. 'true' shows source, 'false' hides source." + }, + { + "type": "bool (optional)", + "name": "locked", + "description": "The new locked status of the source. 'true' keeps it in its current position, 'false' allows movement." + }, + { + "type": "String (optional)", + "name": "bounds.type", + "description": "The new bounds type of the source. Can be \"OBS_BOUNDS_STRETCH\", \"OBS_BOUNDS_SCALE_INNER\", \"OBS_BOUNDS_SCALE_OUTER\", \"OBS_BOUNDS_SCALE_TO_WIDTH\", \"OBS_BOUNDS_SCALE_TO_HEIGHT\", \"OBS_BOUNDS_MAX_ONLY\" or \"OBS_BOUNDS_NONE\"." + }, + { + "type": "int (optional)", + "name": "bounds.alignment", + "description": "The new alignment of the bounding box. (0-2, 4-6, 8-10)" + }, + { + "type": "double (optional)", + "name": "bounds.x", + "description": "The new width of the bounding box." + }, + { + "type": "double (optional)", + "name": "bounds.y", + "description": "The new height of the bounding box." + } + ], + "names": [ + { + "name": "", + "description": "SetSceneItemProperties" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.3.0" + } + ], + "heading": { + "level": 2, + "text": "SetSceneItemProperties" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Reset a scene item.", + "param": [ + "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", + "{String | Object} `item` Scene Item name (if this field is a string) or specification (if it is an object).", + "{String (optional)} `item.name` Scene Item name (if the `item` field is an object)", + "{int (optional)} `item.id` Scene Item ID (if the `item` field is an object)" + ], + "api": "requests", + "name": "ResetSceneItem", + "category": "scene items", + "since": "4.2.0", + "params": [ + { + "type": "String (optional)", + "name": "scene-name", + "description": "Name of the scene the scene item belongs to. Defaults to the current scene." + }, + { + "type": "String | Object", + "name": "item", + "description": "Scene Item name (if this field is a string) or specification (if it is an object)." + }, + { + "type": "String (optional)", + "name": "item.name", + "description": "Scene Item name (if the `item` field is an object)" + }, + { + "type": "int (optional)", + "name": "item.id", + "description": "Scene Item ID (if the `item` field is an object)" + } + ], + "names": [ + { + "name": "", + "description": "ResetSceneItem" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.2.0" + } + ], + "heading": { + "level": 2, + "text": "ResetSceneItem" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Show or hide a specified source item in a specified scene.", + "param": [ + "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the currently active scene.", + "{String} `source` Scene Item name.", + "{boolean} `render` true = shown ; false = hidden" + ], + "api": "requests", + "name": "SetSceneItemRender", + "category": "scene items", + "since": "0.3", + "params": [ + { + "type": "String (optional)", + "name": "scene-name", + "description": "Name of the scene the scene item belongs to. Defaults to the currently active scene." + }, + { + "type": "String", + "name": "source", + "description": "Scene Item name." + }, + { + "type": "boolean", + "name": "render", + "description": "true = shown ; false = hidden" + } + ], + "names": [ + { + "name": "", + "description": "SetSceneItemRender" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "0.3" + } + ], + "heading": { + "level": 2, + "text": "SetSceneItemRender" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Sets the coordinates of a specified source item.", + "param": [ + "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", + "{String} `item` Scene Item name.", + "{double} `x` X coordinate.", + "{double} `y` Y coordinate." + ], + "api": "requests", + "name": "SetSceneItemPosition", + "category": "scene items", + "since": "4.0.0", + "deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.", + "params": [ + { + "type": "String (optional)", + "name": "scene-name", + "description": "Name of the scene the scene item belongs to. Defaults to the current scene." + }, + { + "type": "String", + "name": "item", + "description": "Scene Item name." + }, + { + "type": "double", + "name": "x", + "description": "X coordinate." + }, + { + "type": "double", + "name": "y", + "description": "Y coordinate." + } + ], + "names": [ + { + "name": "", + "description": "SetSceneItemPosition" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "deprecateds": [ + { + "name": "", + "description": "Since 4.3.0. Prefer the use of SetSceneItemProperties." + } + ], + "heading": { + "level": 2, + "text": "SetSceneItemPosition" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Set the transform of the specified source item.", + "param": [ + "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", + "{String} `item` Scene Item name.", + "{double} `x-scale` Width scale factor.", + "{double} `y-scale` Height scale factor.", + "{double} `rotation` Source item rotation (in degrees)." + ], + "api": "requests", + "name": "SetSceneItemTransform", + "category": "scene items", + "since": "4.0.0", + "deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.", + "params": [ + { + "type": "String (optional)", + "name": "scene-name", + "description": "Name of the scene the scene item belongs to. Defaults to the current scene." + }, + { + "type": "String", + "name": "item", + "description": "Scene Item name." + }, + { + "type": "double", + "name": "x-scale", + "description": "Width scale factor." + }, + { + "type": "double", + "name": "y-scale", + "description": "Height scale factor." + }, + { + "type": "double", + "name": "rotation", + "description": "Source item rotation (in degrees)." + } + ], + "names": [ + { + "name": "", + "description": "SetSceneItemTransform" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.0.0" + } + ], + "deprecateds": [ + { + "name": "", + "description": "Since 4.3.0. Prefer the use of SetSceneItemProperties." + } + ], + "heading": { + "level": 2, + "text": "SetSceneItemTransform" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Sets the crop coordinates of the specified source item.", + "param": [ + "{String (optional)} `scene-name` Name of the scene the scene item belongs to. Defaults to the current scene.", + "{String} `item` Scene Item name.", + "{int} `top` Pixel position of the top of the source item.", + "{int} `bottom` Pixel position of the bottom of the source item.", + "{int} `left` Pixel position of the left of the source item.", + "{int} `right` Pixel position of the right of the source item." + ], + "api": "requests", + "name": "SetSceneItemCrop", + "category": "scene items", + "since": "4.1.0", + "deprecated": "Since 4.3.0. Prefer the use of SetSceneItemProperties.", + "params": [ + { + "type": "String (optional)", + "name": "scene-name", + "description": "Name of the scene the scene item belongs to. Defaults to the current scene." + }, + { + "type": "String", + "name": "item", + "description": "Scene Item name." + }, + { + "type": "int", + "name": "top", + "description": "Pixel position of the top of the source item." + }, + { + "type": "int", + "name": "bottom", + "description": "Pixel position of the bottom of the source item." + }, + { + "type": "int", + "name": "left", + "description": "Pixel position of the left of the source item." + }, + { + "type": "int", + "name": "right", + "description": "Pixel position of the right of the source item." + } + ], + "names": [ + { + "name": "", + "description": "SetSceneItemCrop" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.1.0" + } + ], + "deprecateds": [ + { + "name": "", + "description": "Since 4.3.0. Prefer the use of SetSceneItemProperties." + } + ], + "heading": { + "level": 2, + "text": "SetSceneItemCrop" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Deletes a scene item.", + "param": [ + "{String (optional)} `scene` Name of the scene the scene item belongs to. Defaults to the current scene.", + "{Object} `item` Scene item to delete (required)", + "{String} `item.name` Scene Item name (prefer `id`, including both is acceptable).", + "{int} `item.id` Scene Item ID." + ], + "api": "requests", + "name": "DeleteSceneItem", + "category": "scene items", + "since": "4.5.0", + "params": [ + { + "type": "String (optional)", + "name": "scene", + "description": "Name of the scene the scene item belongs to. Defaults to the current scene." + }, + { + "type": "Object", + "name": "item", + "description": "Scene item to delete (required)" + }, + { + "type": "String", + "name": "item.name", + "description": "Scene Item name (prefer `id`, including both is acceptable)." + }, + { + "type": "int", + "name": "item.id", + "description": "Scene Item ID." + } + ], + "names": [ + { + "name": "", + "description": "DeleteSceneItem" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.5.0" + } + ], + "heading": { + "level": 2, + "text": "DeleteSceneItem" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Creates a scene item in a scene. In other words, this is how you add a source into a scene.", + "param": [ + "{String} `sceneName` Name of the scene to create the scene item in", + "{String} `sourceName` Name of the source to be added", + "{boolean} `setVisible` Whether to make the sceneitem visible on creation or not. Default `true`" + ], + "return": "{int} `itemId` Numerical ID of the created scene item", + "api": "requests", + "name": "AddSceneItem", + "category": "scene items", + "since": "unreleased", + "returns": [ + { + "type": "int", + "name": "itemId", + "description": "Numerical ID of the created scene item" + } + ], + "params": [ + { + "type": "String", + "name": "sceneName", + "description": "Name of the scene to create the scene item in" + }, + { + "type": "String", + "name": "sourceName", + "description": "Name of the source to be added" + }, + { + "type": "boolean", + "name": "setVisible", + "description": "Whether to make the sceneitem visible on creation or not. Default `true`" + } + ], + "names": [ + { + "name": "", + "description": "AddSceneItem" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "AddSceneItem" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Duplicates a scene item.", + "param": [ + "{String (optional)} `fromScene` Name of the scene to copy the item from. Defaults to the current scene.", + "{String (optional)} `toScene` Name of the scene to create the item in. Defaults to the current scene.", + "{Object} `item` Scene Item to duplicate from the source scene (required)", + "{String} `item.name` Scene Item name (prefer `id`, including both is acceptable).", + "{int} `item.id` Scene Item ID." + ], + "return": [ + "{String} `scene` Name of the scene where the new item was created", + "{Object} `item` New item info", + "{int} `item.id` New item ID", + "{String} `item.name` New item name" + ], + "api": "requests", + "name": "DuplicateSceneItem", + "category": "scene items", + "since": "4.5.0", + "returns": [ + { + "type": "String", + "name": "scene", + "description": "Name of the scene where the new item was created" + }, + { + "type": "Object", + "name": "item", + "description": "New item info" + }, + { + "type": "int", + "name": "item.id", + "description": "New item ID" + }, + { + "type": "String", + "name": "item.name", + "description": "New item name" + } + ], + "params": [ + { + "type": "String (optional)", + "name": "fromScene", + "description": "Name of the scene to copy the item from. Defaults to the current scene." + }, + { + "type": "String (optional)", + "name": "toScene", + "description": "Name of the scene to create the item in. Defaults to the current scene." + }, + { + "type": "Object", + "name": "item", + "description": "Scene Item to duplicate from the source scene (required)" + }, + { + "type": "String", + "name": "item.name", + "description": "Scene Item name (prefer `id`, including both is acceptable)." + }, + { + "type": "int", + "name": "item.id", + "description": "Scene Item ID." + } + ], + "names": [ + { + "name": "", + "description": "DuplicateSceneItem" + } + ], + "categories": [ + { + "name": "", + "description": "scene items" + } + ], + "sinces": [ + { + "name": "", + "description": "4.5.0" + } + ], + "heading": { + "level": 2, + "text": "DuplicateSceneItem" + }, + "lead": "", + "type": "class", + "examples": [] + } + ], + "scenes": [ + { + "subheads": [], + "description": "Switch to the specified scene.", + "param": "{String} `scene-name` Name of the scene to switch to.", + "api": "requests", + "name": "SetCurrentScene", + "category": "scenes", + "since": "0.3", + "params": [ + { + "type": "String", + "name": "scene-name", + "description": "Name of the scene to switch to." + } + ], + "names": [ + { + "name": "", + "description": "SetCurrentScene" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "0.3" + } + ], + "heading": { + "level": 2, + "text": "SetCurrentScene" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the current scene's name and source items.", + "return": [ + "{String} `name` Name of the currently active scene.", + "{Array} `sources` Ordered list of the current scene's source items." + ], + "api": "requests", + "name": "GetCurrentScene", + "category": "scenes", + "since": "0.3", + "returns": [ + { + "type": "String", + "name": "name", + "description": "Name of the currently active scene." + }, + { + "type": "Array", + "name": "sources", + "description": "Ordered list of the current scene's source items." + } + ], + "names": [ + { + "name": "", + "description": "GetCurrentScene" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "0.3" + } + ], + "heading": { + "level": 2, + "text": "GetCurrentScene" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get a list of scenes in the currently active profile.", + "return": [ + "{String} `current-scene` Name of the currently active scene.", + "{Array} `scenes` Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information)." + ], + "api": "requests", + "name": "GetSceneList", + "category": "scenes", + "since": "0.3", + "returns": [ + { + "type": "String", + "name": "current-scene", + "description": "Name of the currently active scene." + }, + { + "type": "Array", + "name": "scenes", + "description": "Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information)." + } + ], + "names": [ + { + "name": "", + "description": "GetSceneList" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "0.3" + } + ], + "heading": { + "level": 2, + "text": "GetSceneList" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Create a new scene scene.", + "param": "{String} `sceneName` Name of the scene to create.", + "api": "requests", + "name": "CreateScene", + "category": "scenes", + "since": "4.8.0", + "params": [ + { + "type": "String", + "name": "sceneName", + "description": "Name of the scene to create." + } + ], + "names": [ + { + "name": "", + "description": "CreateScene" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "CreateScene" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Changes the order of scene items in the requested scene.", + "param": [ + "{String (optional)} `scene` Name of the scene to reorder (defaults to current).", + "{Array} `items` Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene", + "{int (optional)} `items.*.id` Id of a specific scene item. Unique on a scene by scene basis.", + "{String (optional)} `items.*.name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene." + ], + "api": "requests", + "name": "ReorderSceneItems", + "category": "scenes", + "since": "4.5.0", + "params": [ + { + "type": "String (optional)", + "name": "scene", + "description": "Name of the scene to reorder (defaults to current)." + }, + { + "type": "Array", + "name": "items", + "description": "Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene" + }, + { + "type": "int (optional)", + "name": "items.*.id", + "description": "Id of a specific scene item. Unique on a scene by scene basis." + }, + { + "type": "String (optional)", + "name": "items.*.name", + "description": "Name of a scene item. Sufficiently unique if no scene items share sources within the scene." + } + ], + "names": [ + { + "name": "", + "description": "ReorderSceneItems" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "4.5.0" + } + ], + "heading": { + "level": 2, + "text": "ReorderSceneItems" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Set a scene to use a specific transition override.", + "param": [ + "{String} `sceneName` Name of the scene to switch to.", + "{String} `transitionName` Name of the transition to use.", + "{int (Optional)} `transitionDuration` Duration in milliseconds of the transition if transition is not fixed. Defaults to the current duration specified in the UI if there is no current override and this value is not given." + ], + "api": "requests", + "name": "SetSceneTransitionOverride", + "category": "scenes", + "since": "4.8.0", + "params": [ + { + "type": "String", + "name": "sceneName", + "description": "Name of the scene to switch to." + }, + { + "type": "String", + "name": "transitionName", + "description": "Name of the transition to use." + }, + { + "type": "int (Optional)", + "name": "transitionDuration", + "description": "Duration in milliseconds of the transition if transition is not fixed. Defaults to the current duration specified in the UI if there is no current override and this value is not given." + } + ], + "names": [ + { + "name": "", + "description": "SetSceneTransitionOverride" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "SetSceneTransitionOverride" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Remove any transition override on a scene.", + "param": "{String} `sceneName` Name of the scene to switch to.", + "api": "requests", + "name": "RemoveSceneTransitionOverride", + "category": "scenes", + "since": "4.8.0", + "params": [ + { + "type": "String", + "name": "sceneName", + "description": "Name of the scene to switch to." + } + ], + "names": [ + { + "name": "", + "description": "RemoveSceneTransitionOverride" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "RemoveSceneTransitionOverride" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the current scene transition override.", + "param": "{String} `sceneName` Name of the scene to switch to.", + "return": [ + "{String} `transitionName` Name of the current overriding transition. Empty string if no override is set.", + "{int} `transitionDuration` Transition duration. `-1` if no override is set." + ], + "api": "requests", + "name": "GetSceneTransitionOverride", + "category": "scenes", + "since": "4.8.0", + "returns": [ + { + "type": "String", + "name": "transitionName", + "description": "Name of the current overriding transition. Empty string if no override is set." + }, + { + "type": "int", + "name": "transitionDuration", + "description": "Transition duration. `-1` if no override is set." + } + ], + "params": [ + { + "type": "String", + "name": "sceneName", + "description": "Name of the scene to switch to." + } + ], + "names": [ + { + "name": "", + "description": "GetSceneTransitionOverride" + } + ], + "categories": [ + { + "name": "", + "description": "scenes" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "GetSceneTransitionOverride" + }, + "lead": "", + "type": "class", + "examples": [] + } + ], "streaming": [ { "subheads": [], @@ -7770,7 +9572,7 @@ }, { "subheads": [], - "description": "Toggle streaming on or off.", + "description": "Toggle streaming on or off (depending on the current stream state).", "api": "requests", "name": "StartStopStreaming", "category": "streaming", @@ -8124,7 +9926,7 @@ }, { "subheads": [], - "description": "Send the provided text as embedded CEA-608 caption data.\nAs of OBS Studio 23.1, captions are not yet available on Linux.", + "description": "Send the provided text as embedded CEA-608 caption data.", "param": "{String} `text` Captions text", "api": "requests", "name": "SendCaptions", @@ -8419,7 +10221,7 @@ }, { "subheads": [], - "description": "Toggles Studio Mode.", + "description": "Toggles Studio Mode (depending on the current state of studio mode).", "api": "requests", "name": "ToggleStudioMode", "category": "studio mode", @@ -8678,6 +10480,153 @@ "lead": "", "type": "class", "examples": [] + }, + { + "subheads": [], + "description": "Get the position of the current transition.", + "return": "{double} `position` current transition position. This value will be between 0.0 and 1.0. Note: Transition returns 1.0 when not active.", + "api": "requests", + "name": "GetTransitionPosition", + "category": "transitions", + "since": "4.8.0", + "returns": [ + { + "type": "double", + "name": "position", + "description": "current transition position. This value will be between 0.0 and 1.0. Note: Transition returns 1.0 when not active." + } + ], + "names": [ + { + "name": "", + "description": "GetTransitionPosition" + } + ], + "categories": [ + { + "name": "", + "description": "transitions" + } + ], + "sinces": [ + { + "name": "", + "description": "4.8.0" + } + ], + "heading": { + "level": 2, + "text": "GetTransitionPosition" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Get the current settings of a transition", + "param": "{String} `transitionName` Transition name", + "return": "{Object} `transitionSettings` Current transition settings", + "api": "requests", + "name": "GetTransitionSettings", + "category": "transitions", + "since": "unreleased", + "returns": [ + { + "type": "Object", + "name": "transitionSettings", + "description": "Current transition settings" + } + ], + "params": [ + { + "type": "String", + "name": "transitionName", + "description": "Transition name" + } + ], + "names": [ + { + "name": "", + "description": "GetTransitionSettings" + } + ], + "categories": [ + { + "name": "", + "description": "transitions" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "GetTransitionSettings" + }, + "lead": "", + "type": "class", + "examples": [] + }, + { + "subheads": [], + "description": "Change the current settings of a transition", + "param": [ + "{String} `transitionName` Transition name", + "{Object} `transitionSettings` Transition settings (they can be partial)" + ], + "return": "{Object} `transitionSettings` Updated transition settings", + "api": "requests", + "name": "SetTransitionSettings", + "category": "transitions", + "since": "unreleased", + "returns": [ + { + "type": "Object", + "name": "transitionSettings", + "description": "Updated transition settings" + } + ], + "params": [ + { + "type": "String", + "name": "transitionName", + "description": "Transition name" + }, + { + "type": "Object", + "name": "transitionSettings", + "description": "Transition settings (they can be partial)" + } + ], + "names": [ + { + "name": "", + "description": "SetTransitionSettings" + } + ], + "categories": [ + { + "name": "", + "description": "transitions" + } + ], + "sinces": [ + { + "name": "", + "description": "unreleased" + } + ], + "heading": { + "level": 2, + "text": "SetTransitionSettings" + }, + "lead": "", + "type": "class", + "examples": [] } ] } diff --git a/docs/generated/protocol.md b/docs/generated/protocol.md index e5f47ec1..7d3f7610 100644 --- a/docs/generated/protocol.md +++ b/docs/generated/protocol.md @@ -1,10 +1,10 @@ -# obs-websocket 4.7.0 protocol reference +# obs-websocket 4.8.0 protocol reference # General Introduction Messages are exchanged between the client and the server as JSON objects. -This protocol is based on the original OBS Remote protocol created by Bill Hamilton, with new commands specific to OBS Studio. +This protocol is based on the original OBS Remote protocol created by Bill Hamilton, with new commands specific to OBS Studio. As of v5.0.0, backwards compatability with the protocol will not be kept. # Authentication `obs-websocket` uses SHA256 to transmit credentials. @@ -35,6 +35,8 @@ auth_response_hash = binary_sha256(auth_response_string) auth_response = base64_encode(auth_response_hash) ``` +You can also refer to any of the client libraries listed on the [README](README.md) for examples of how to authenticate. + @@ -92,6 +94,8 @@ auth_response = base64_encode(auth_response_hash) + [SourceDestroyed](#sourcedestroyed) + [SourceVolumeChanged](#sourcevolumechanged) + [SourceMuteStateChanged](#sourcemutestatechanged) + + [SourceAudioDeactivated](#sourceaudiodeactivated) + + [SourceAudioActivated](#sourceaudioactivated) + [SourceAudioSyncOffsetChanged](#sourceaudiosyncoffsetchanged) + [SourceAudioMixersChanged](#sourceaudiomixerschanged) + [SourceRenamed](#sourcerenamed) @@ -99,6 +103,15 @@ auth_response = base64_encode(auth_response_hash) + [SourceFilterRemoved](#sourcefilterremoved) + [SourceFilterVisibilityChanged](#sourcefiltervisibilitychanged) + [SourceFiltersReordered](#sourcefiltersreordered) + * [Media](#media) + + [MediaPlaying](#mediaplaying) + + [MediaPaused](#mediapaused) + + [MediaRestarted](#mediarestarted) + + [MediaStopped](#mediastopped) + + [MediaNext](#medianext) + + [MediaPrevious](#mediaprevious) + + [MediaStarted](#mediastarted) + + [MediaEnded](#mediaended) * [Scene Items](#scene-items) + [SourceOrderChanged](#sourceorderchanged) + [SceneItemAdded](#sceneitemadded) @@ -123,48 +136,21 @@ auth_response = base64_encode(auth_response_hash) + [BroadcastCustomMessage](#broadcastcustommessage-1) + [GetVideoInfo](#getvideoinfo) + [OpenProjector](#openprojector) - * [Outputs](#outputs) - + [ListOutputs](#listoutputs) - + [GetOutputInfo](#getoutputinfo) - + [StartOutput](#startoutput) - + [StopOutput](#stopoutput) - * [Profiles](#profiles-1) - + [SetCurrentProfile](#setcurrentprofile) - + [GetCurrentProfile](#getcurrentprofile) - + [ListProfiles](#listprofiles) - * [Recording](#recording-1) - + [StartStopRecording](#startstoprecording) - + [StartRecording](#startrecording) - + [StopRecording](#stoprecording) - + [PauseRecording](#pauserecording) - + [ResumeRecording](#resumerecording) - + [SetRecordingFolder](#setrecordingfolder) - + [GetRecordingFolder](#getrecordingfolder) - * [Replay Buffer](#replay-buffer-1) - + [StartStopReplayBuffer](#startstopreplaybuffer) - + [StartReplayBuffer](#startreplaybuffer) - + [StopReplayBuffer](#stopreplaybuffer) - + [SaveReplayBuffer](#savereplaybuffer) - * [Scene Collections](#scene-collections) - + [SetCurrentSceneCollection](#setcurrentscenecollection) - + [GetCurrentSceneCollection](#getcurrentscenecollection) - + [ListSceneCollections](#listscenecollections) - * [Scene Items](#scene-items-1) - + [GetSceneItemProperties](#getsceneitemproperties) - + [SetSceneItemProperties](#setsceneitemproperties) - + [ResetSceneItem](#resetsceneitem) - + [SetSceneItemRender](#setsceneitemrender) - + [SetSceneItemPosition](#setsceneitemposition) - + [SetSceneItemTransform](#setsceneitemtransform) - + [SetSceneItemCrop](#setsceneitemcrop) - + [DeleteSceneItem](#deletesceneitem) - + [DuplicateSceneItem](#duplicatesceneitem) - * [Scenes](#scenes-1) - + [SetCurrentScene](#setcurrentscene) - + [GetCurrentScene](#getcurrentscene) - + [GetSceneList](#getscenelist) - + [ReorderSceneItems](#reordersceneitems) + + [TriggerHotkeyByName](#triggerhotkeybyname) + + [TriggerHotkeyBySequence](#triggerhotkeybysequence) + * [Media Control](#media-control) + + [PlayPauseMedia](#playpausemedia) + + [RestartMedia](#restartmedia) + + [StopMedia](#stopmedia) + + [NextMedia](#nextmedia) + + [PreviousMedia](#previousmedia) + + [GetMediaDuration](#getmediaduration) + + [GetMediaTime](#getmediatime) + + [SetMediaTime](#setmediatime) + + [ScrubMedia](#scrubmedia) + + [GetMediaState](#getmediastate) * [Sources](#sources-1) + + [GetMediaSourcesList](#getmediasourceslist) + [GetSourcesList](#getsourceslist) + [GetSourceTypesList](#getsourcetypeslist) + [GetVolume](#getvolume) @@ -172,6 +158,8 @@ auth_response = base64_encode(auth_response_hash) + [GetMute](#getmute) + [SetMute](#setmute) + [ToggleMute](#togglemute) + + [GetAudioActive](#getaudioactive) + + [SetSourceName](#setsourcename) + [SetSyncOffset](#setsyncoffset) + [GetSyncOffset](#getsyncoffset) + [GetSourceSettings](#getsourcesettings) @@ -191,7 +179,58 @@ auth_response = base64_encode(auth_response_hash) + [MoveSourceFilter](#movesourcefilter) + [SetSourceFilterSettings](#setsourcefiltersettings) + [SetSourceFilterVisibility](#setsourcefiltervisibility) + + [GetAudioMonitorType](#getaudiomonitortype) + + [SetAudioMonitorType](#setaudiomonitortype) + [TakeSourceScreenshot](#takesourcescreenshot) + * [Outputs](#outputs) + + [ListOutputs](#listoutputs) + + [GetOutputInfo](#getoutputinfo) + + [StartOutput](#startoutput) + + [StopOutput](#stopoutput) + * [Profiles](#profiles-1) + + [SetCurrentProfile](#setcurrentprofile) + + [GetCurrentProfile](#getcurrentprofile) + + [ListProfiles](#listprofiles) + * [Recording](#recording-1) + + [GetRecordingStatus](#getrecordingstatus) + + [StartStopRecording](#startstoprecording) + + [StartRecording](#startrecording) + + [StopRecording](#stoprecording) + + [PauseRecording](#pauserecording) + + [ResumeRecording](#resumerecording) + + [SetRecordingFolder](#setrecordingfolder) + + [GetRecordingFolder](#getrecordingfolder) + * [Replay Buffer](#replay-buffer-1) + + [GetReplayBufferStatus](#getreplaybufferstatus) + + [StartStopReplayBuffer](#startstopreplaybuffer) + + [StartReplayBuffer](#startreplaybuffer) + + [StopReplayBuffer](#stopreplaybuffer) + + [SaveReplayBuffer](#savereplaybuffer) + * [Scene Collections](#scene-collections) + + [SetCurrentSceneCollection](#setcurrentscenecollection) + + [GetCurrentSceneCollection](#getcurrentscenecollection) + + [ListSceneCollections](#listscenecollections) + * [Scene Items](#scene-items-1) + + [GetSceneItemList](#getsceneitemlist) + + [GetSceneItemProperties](#getsceneitemproperties) + + [SetSceneItemProperties](#setsceneitemproperties) + + [ResetSceneItem](#resetsceneitem) + + [SetSceneItemRender](#setsceneitemrender) + + [SetSceneItemPosition](#setsceneitemposition) + + [SetSceneItemTransform](#setsceneitemtransform) + + [SetSceneItemCrop](#setsceneitemcrop) + + [DeleteSceneItem](#deletesceneitem) + + [AddSceneItem](#addsceneitem) + + [DuplicateSceneItem](#duplicatesceneitem) + * [Scenes](#scenes-1) + + [SetCurrentScene](#setcurrentscene) + + [GetCurrentScene](#getcurrentscene) + + [GetSceneList](#getscenelist) + + [CreateScene](#createscene) + + [ReorderSceneItems](#reordersceneitems) + + [SetSceneTransitionOverride](#setscenetransitionoverride) + + [RemoveSceneTransitionOverride](#removescenetransitionoverride) + + [GetSceneTransitionOverride](#getscenetransitionoverride) * [Streaming](#streaming-1) + [GetStreamingStatus](#getstreamingstatus) + [StartStopStreaming](#startstopstreaming) @@ -215,6 +254,9 @@ auth_response = base64_encode(auth_response_hash) + [SetCurrentTransition](#setcurrenttransition) + [SetTransitionDuration](#settransitionduration) + [GetTransitionDuration](#gettransitionduration) + + [GetTransitionPosition](#gettransitionposition) + + [GetTransitionSettings](#gettransitionsettings) + + [SetTransitionSettings](#settransitionsettings) @@ -244,8 +286,8 @@ These are complex types, such as `Source` and `Scene`, which are used as argumen ## SceneItemTransform | Name | Type | Description | | ---- | :---: | ------------| -| `position.x` | _int_ | The x position of the scene item from the left. | -| `position.y` | _int_ | The y position of the scene item from the top. | +| `position.x` | _double_ | The x position of the scene item from the left. | +| `position.y` | _double_ | The y position of the scene item from the top. | | `position.alignment` | _int_ | The point on the scene item that the item is manipulated from. | | `rotation` | _double_ | The clockwise rotation of the scene item in degrees around the point of alignment. | | `scale.x` | _double_ | The x-scale factor of the scene item. | @@ -344,8 +386,9 @@ Indicates a scene change. - Added in v0.3 -The scene list has been modified. -Scenes have been added, removed, or renamed. + + +Note: This event is not fired when the scenes are reordered. **Response Items:** @@ -580,7 +623,7 @@ _No additional response items._ - Added in v0.3 -Emit every 2 seconds. +Emitted every 2 seconds when stream is active. **Response Items:** @@ -763,7 +806,7 @@ _No additional response items._ ### Heartbeat -- Added in v +- Added in vv0.3 Emitted every 2 seconds after enabling it by calling SetHeartbeat. @@ -792,7 +835,7 @@ Emitted every 2 seconds after enabling it by calling SetHeartbeat. - Added in v4.7.0 -A custom broadcast message was received +A custom broadcast message, sent by the server, requested by one of the websocket clients. **Response Items:** @@ -875,6 +918,38 @@ A source has been muted or unmuted. | `muted` | _boolean_ | Mute status of the source | +--- + +### SourceAudioDeactivated + + +- Unreleased + +A source has removed audio. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | + + +--- + +### SourceAudioActivated + + +- Unreleased + +A source has added audio. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | + + --- ### SourceAudioSyncOffsetChanged @@ -927,6 +1002,7 @@ A source has been renamed. | ---- | :---: | ------------| | `previousName` | _String_ | Previous source name | | `newName` | _String_ | New source name | +| `sourceType` | _String_ | Type of source (input, scene, filter, transition) | --- @@ -1001,6 +1077,161 @@ Filters in a source have been reordered. | `filters` | _Array<Object>_ | Ordered Filters list | | `filters.*.name` | _String_ | Filter name | | `filters.*.type` | _String_ | Filter type | +| `filters.*.enabled` | _boolean_ | Filter visibility status | + + +--- + +## Media + +### MediaPlaying + + +- Unreleased + + + +Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | + + +--- + +### MediaPaused + + +- Unreleased + + + +Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | + + +--- + +### MediaRestarted + + +- Unreleased + + + +Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | + + +--- + +### MediaStopped + + +- Unreleased + + + +Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | + + +--- + +### MediaNext + + +- Unreleased + + + +Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | + + +--- + +### MediaPrevious + + +- Unreleased + + + +Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | + + +--- + +### MediaStarted + + +- Unreleased + + + +Note: These events are emitted by the OBS sources themselves. For example when the media file starts playing. The behavior depends on the type of media source being used. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | + + +--- + +### MediaEnded + + +- Unreleased + + + +Note: These events are emitted by the OBS sources themselves. For example when the media file ends. The behavior depends on the type of media source being used. + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name | +| `sourceKind` | _String_ | The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) | --- @@ -1012,7 +1243,7 @@ Filters in a source have been reordered. - Added in v4.0.0 -Scene items have been reordered. +Scene items within a scene have been reordered. **Response Items:** @@ -1031,7 +1262,7 @@ Scene items have been reordered. - Added in v4.0.0 -An item has been added to the current scene. +A scene item has been added to a scene. **Response Items:** @@ -1049,7 +1280,7 @@ An item has been added to the current scene. - Added in v4.0.0 -An item has been removed from the current scene. +A scene item has been removed from a scene. **Response Items:** @@ -1067,7 +1298,7 @@ An item has been removed from the current scene. - Added in v4.0.0 -An item's visibility has been toggled. +A scene item's visibility has been toggled. **Response Items:** @@ -1086,7 +1317,7 @@ An item's visibility has been toggled. - Added in v4.8.0 -An item's locked status has been toggled. +A scene item's locked status has been toggled. **Response Items:** @@ -1105,7 +1336,7 @@ An item's locked status has been toggled. - Added in v4.6.0 -An item's transform has been changed. +A scene item's transform has been changed. **Response Items:** @@ -1201,7 +1432,7 @@ Requests are sent by the client and require at least the following two fields: Once a request is sent, the server will return a JSON response with at least the following fields: - `message-id` _String_: The client defined identifier specified in the request. - `status` _String_: Response status, will be one of the following: `ok`, `error` -- `error` _String_: An error message accompanying an `error` status. +- `error` _String (Optional)_: An error message accompanying an `error` status. Additional information may be required/returned depending on the request type. See below for more information. @@ -1277,6 +1508,7 @@ _No additional response items._ ### SetHeartbeat +- **⚠️ Deprecated. Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0. ⚠️** - Added in v4.3.0 @@ -1350,7 +1582,7 @@ _No specified parameters._ | Name | Type | Description | | ---- | :---: | ------------| -| `stats` | _OBSStats_ | OBS stats | +| `stats` | _OBSStats_ | [OBS stats](#obsstats) | --- @@ -1415,9 +1647,9 @@ Open a projector window or create a projector on a monitor. Requires OBS v24.0.4 | Name | Type | Description | | ---- | :---: | ------------| -| `type` | _String (Optional)_ | Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive). | +| `type` | _String (Optional)_ | Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive). | | `monitor` | _int (Optional)_ | Monitor to open the projector on. If -1 or omitted, opens a window. | -| `geometry` | _String (Optional)_ | Size and position of the projector window (only if monitor is -1). Encoded in Base64 using Qt's geometry encoding (https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors. | +| `geometry` | _String (Optional)_ | Size and position of the projector window (only if monitor is -1). Encoded in Base64 using [Qt's geometry encoding](https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors. | | `name` | _String (Optional)_ | Name of the source or scene to be displayed (ignored for other projector types). | @@ -1427,63 +1659,18 @@ _No additional response items._ --- -## Outputs - -### ListOutputs +### TriggerHotkeyByName -- Added in v4.7.0 +- Unreleased -List existing outputs - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `outputs` | _Array<Output>_ | Outputs list | - - ---- - -### GetOutputInfo - - -- Added in v4.7.0 - -Get information about a single output +Executes hotkey routine, identified by hotkey unique name **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `outputName` | _String_ | Output name | - - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `outputInfo` | _Output_ | Output info | - - ---- - -### StartOutput - - -- Added in v4.7.0 - -Start an output - -**Request Fields:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `outputName` | _String_ | Output name | +| `hotkeyName` | _String_ | Unique name of the hotkey, as defined when registering the hotkey (e.g. "ReplayBuffer.Save") | **Response Items:** @@ -1492,19 +1679,23 @@ _No additional response items._ --- -### StopOutput +### TriggerHotkeyBySequence -- Added in v4.7.0 +- Unreleased -Stop an output +Executes hotkey routine, identified by bound combination of keys. A single key combination might trigger multiple hotkey routines depending on user settings **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `outputName` | _String_ | Output name | -| `force` | _boolean (optional)_ | Force stop (default: false) | +| `keyId` | _String_ | Main key identifier (e.g. `OBS_KEY_A` for key "A"). Available identifiers [here](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-hotkeys.h) | +| `keyModifiers` | _Object (Optional)_ | Optional key modifiers object. False entries can be ommitted | +| `keyModifiers.shift` | _boolean_ | Trigger Shift Key | +| `keyModifiers.alt` | _boolean_ | Trigger Alt Key | +| `keyModifiers.control` | _boolean_ | Trigger Control (Ctrl) Key | +| `keyModifiers.command` | _boolean_ | Trigger Command Key (Mac) | **Response Items:** @@ -1513,20 +1704,21 @@ _No additional response items._ --- -## Profiles +## Media Control -### SetCurrentProfile +### PlayPauseMedia -- Added in v4.0.0 +- Unreleased -Set the currently active profile. +Pause or play a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `profile-name` | _String_ | Name of the desired profile. | +| `sourceName` | _String_ | Source name. | +| `playPause` | _boolean_ | Whether to pause or play the source. `false` for play, `true` for pause. | **Response Items:** @@ -1535,153 +1727,18 @@ _No additional response items._ --- -### GetCurrentProfile +### RestartMedia -- Added in v4.0.0 +- Unreleased -Get the name of the current profile. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `profile-name` | _String_ | Name of the currently active profile. | - - ---- - -### ListProfiles - - -- Added in v4.0.0 - -Get a list of available profiles. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `profiles` | _Array<Object>_ | List of available profiles. | - - ---- - -## Recording - -### StartStopRecording - - -- Added in v0.3 - -Toggle recording on or off. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### StartRecording - - -- Added in v4.1.0 - -Start recording. -Will return an `error` if recording is already active. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### StopRecording - - -- Added in v4.1.0 - -Stop recording. -Will return an `error` if recording is not active. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### PauseRecording - - -- Added in v4.7.0 - -Pause the current recording. -Returns an error if recording is not active or already paused. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### ResumeRecording - - -- Added in v4.7.0 - -Resume/unpause the current recording (if paused). -Returns an error if recording is not active or not paused. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### SetRecordingFolder - - -- Added in v4.1.0 - - - -Please note: if `SetRecordingFolder` is called while a recording is -in progress, the change won't be applied immediately and will be -effective on the next recording. +Restart a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `rec-folder` | _String_ | Path of the recording folder. | +| `sourceName` | _String_ | Source name. | **Response Items:** @@ -1690,117 +1747,18 @@ _No additional response items._ --- -### GetRecordingFolder +### StopMedia -- Added in v4.1.0 +- Unreleased -Get the path of the current recording folder. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `rec-folder` | _String_ | Path of the recording folder. | - - ---- - -## Replay Buffer - -### StartStopReplayBuffer - - -- Added in v4.2.0 - -Toggle the Replay Buffer on/off. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### StartReplayBuffer - - -- Added in v4.2.0 - -Start recording into the Replay Buffer. -Will return an `error` if the Replay Buffer is already active or if the -"Save Replay Buffer" hotkey is not set in OBS' settings. -Setting this hotkey is mandatory, even when triggering saves only -through obs-websocket. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### StopReplayBuffer - - -- Added in v4.2.0 - -Stop recording into the Replay Buffer. -Will return an `error` if the Replay Buffer is not active. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -### SaveReplayBuffer - - -- Added in v4.2.0 - -Flush and save the contents of the Replay Buffer to disk. This is -basically the same as triggering the "Save Replay Buffer" hotkey. -Will return an `error` if the Replay Buffer is not active. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -_No additional response items._ - ---- - -## Scene Collections - -### SetCurrentSceneCollection - - -- Added in v4.0.0 - -Change the active scene collection. +Stop a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `sc-name` | _String_ | Name of the desired scene collection. | +| `sourceName` | _String_ | Source name. | **Response Items:** @@ -1809,132 +1767,18 @@ _No additional response items._ --- -### GetCurrentSceneCollection +### NextMedia -- Added in v4.0.0 +- Unreleased -Get the name of the current scene collection. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `sc-name` | _String_ | Name of the currently active scene collection. | - - ---- - -### ListSceneCollections - - -- Added in v4.0.0 - -List available scene collections - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `scene-collections` | _Array<String>_ | Scene collections list | - - ---- - -## Scene Items - -### GetSceneItemProperties - - -- Added in v4.3.0 - -Gets the scene specific properties of the specified source item. -Coordinates are relative to the item's parent (the scene or group it belongs to). +Skip to the next media item in the playlist. Supports only vlc media source (as of OBS v25.0.8) **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | -| `item` | _String \| Object_ | Scene Item name (if this field is a string) or specification (if it is an object). | -| `item.name` | _String (optional)_ | Scene Item name (if the `item` field is an object) | -| `item.id` | _int (optional)_ | Scene Item ID (if the `item` field is an object) | - - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `name` | _String_ | Scene Item name. | -| `itemId` | _int_ | Scene Item ID. | -| `position.x` | _int_ | The x position of the source from the left. | -| `position.y` | _int_ | The y position of the source from the top. | -| `position.alignment` | _int_ | The point on the source that the item is manipulated from. | -| `rotation` | _double_ | The clockwise rotation of the item in degrees around the point of alignment. | -| `scale.x` | _double_ | The x-scale factor of the source. | -| `scale.y` | _double_ | The y-scale factor of the source. | -| `crop.top` | _int_ | The number of pixels cropped off the top of the source before scaling. | -| `crop.right` | _int_ | The number of pixels cropped off the right of the source before scaling. | -| `crop.bottom` | _int_ | The number of pixels cropped off the bottom of the source before scaling. | -| `crop.left` | _int_ | The number of pixels cropped off the left of the source before scaling. | -| `visible` | _bool_ | If the source is visible. | -| `muted` | _bool_ | If the source is muted. | -| `locked` | _bool_ | If the source's transform is locked. | -| `bounds.type` | _String_ | Type of bounding box. Can be "OBS_BOUNDS_STRETCH", "OBS_BOUNDS_SCALE_INNER", "OBS_BOUNDS_SCALE_OUTER", "OBS_BOUNDS_SCALE_TO_WIDTH", "OBS_BOUNDS_SCALE_TO_HEIGHT", "OBS_BOUNDS_MAX_ONLY" or "OBS_BOUNDS_NONE". | -| `bounds.alignment` | _int_ | Alignment of the bounding box. | -| `bounds.x` | _double_ | Width of the bounding box. | -| `bounds.y` | _double_ | Height of the bounding box. | -| `sourceWidth` | _int_ | Base width (without scaling) of the source | -| `sourceHeight` | _int_ | Base source (without scaling) of the source | -| `width` | _double_ | Scene item width (base source width multiplied by the horizontal scaling factor) | -| `height` | _double_ | Scene item height (base source height multiplied by the vertical scaling factor) | -| `alignment` | _int_ | The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis. | -| `parentGroupName` | _String (optional)_ | Name of the item's parent (if this item belongs to a group) | -| `groupChildren` | _Array<SceneItemTransform> (optional)_ | List of children (if this item is a group) | - - ---- - -### SetSceneItemProperties - - -- Added in v4.3.0 - -Sets the scene specific properties of a source. Unspecified properties will remain unchanged. -Coordinates are relative to the item's parent (the scene or group it belongs to). - -**Request Fields:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `scene-name` | _String (optional)_ | Name of the scene the source item belongs to. Defaults to the current scene. | -| `item` | _String \| Object_ | Scene Item name (if this field is a string) or specification (if it is an object). | -| `item.name` | _String (optional)_ | Scene Item name (if the `item` field is an object) | -| `item.id` | _int (optional)_ | Scene Item ID (if the `item` field is an object) | -| `position.x` | _int (optional)_ | The new x position of the source. | -| `position.y` | _int (optional)_ | The new y position of the source. | -| `position.alignment` | _int (optional)_ | The new alignment of the source. | -| `rotation` | _double (optional)_ | The new clockwise rotation of the item in degrees. | -| `scale.x` | _double (optional)_ | The new x scale of the item. | -| `scale.y` | _double (optional)_ | The new y scale of the item. | -| `crop.top` | _int (optional)_ | The new amount of pixels cropped off the top of the source before scaling. | -| `crop.bottom` | _int (optional)_ | The new amount of pixels cropped off the bottom of the source before scaling. | -| `crop.left` | _int (optional)_ | The new amount of pixels cropped off the left of the source before scaling. | -| `crop.right` | _int (optional)_ | The new amount of pixels cropped off the right of the source before scaling. | -| `visible` | _bool (optional)_ | The new visibility of the source. 'true' shows source, 'false' hides source. | -| `locked` | _bool (optional)_ | The new locked status of the source. 'true' keeps it in its current position, 'false' allows movement. | -| `bounds.type` | _String (optional)_ | The new bounds type of the source. Can be "OBS_BOUNDS_STRETCH", "OBS_BOUNDS_SCALE_INNER", "OBS_BOUNDS_SCALE_OUTER", "OBS_BOUNDS_SCALE_TO_WIDTH", "OBS_BOUNDS_SCALE_TO_HEIGHT", "OBS_BOUNDS_MAX_ONLY" or "OBS_BOUNDS_NONE". | -| `bounds.alignment` | _int (optional)_ | The new alignment of the bounding box. (0-2, 4-6, 8-10) | -| `bounds.x` | _double (optional)_ | The new width of the bounding box. | -| `bounds.y` | _double (optional)_ | The new height of the bounding box. | +| `sourceName` | _String_ | Source name. | **Response Items:** @@ -1943,21 +1787,18 @@ _No additional response items._ --- -### ResetSceneItem +### PreviousMedia -- Added in v4.2.0 +- Unreleased -Reset a scene item. +Go to the previous media item in the playlist. Supports only vlc media source (as of OBS v25.0.8) **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | -| `item` | _String \| Object_ | Scene Item name (if this field is a string) or specification (if it is an object). | -| `item.name` | _String (optional)_ | Scene Item name (if the `item` field is an object) | -| `item.id` | _int (optional)_ | Scene Item ID (if the `item` field is an object) | +| `sourceName` | _String_ | Source name. | **Response Items:** @@ -1966,21 +1807,66 @@ _No additional response items._ --- -### SetSceneItemRender +### GetMediaDuration -- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️** -- Added in v0.3 +- Unreleased -Show or hide a specified source item in a specified scene. +Get the length of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +Note: For some reason, for the first 5 or so seconds that the media is playing, the total duration can be off by upwards of 50ms. **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the currently active scene. | -| `source` | _String_ | Scene Item name. | -| `render` | _boolean_ | true = shown ; false = hidden | +| `sourceName` | _String_ | Source name. | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `mediaDuration` | _int_ | The total length of media in milliseconds.. | + + +--- + +### GetMediaTime + + +- Unreleased + +Get the current timestamp of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name. | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `timestamp` | _int_ | The time in milliseconds since the start of the media. | + + +--- + +### SetMediaTime + + +- Unreleased + +Set the timestamp of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name. | +| `timestamp` | _int_ | Milliseconds to set the timestamp to. | **Response Items:** @@ -1989,22 +1875,20 @@ _No additional response items._ --- -### SetSceneItemPosition +### ScrubMedia -- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️** -- Added in v4.0.0 +- Unreleased -Sets the coordinates of a specified source item. +Scrub media using a supplied offset. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +Note: Due to processing/network delays, this request is not perfect. The processing rate of this request has also not been tested. **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | -| `item` | _String_ | Scene Item name. | -| `x` | _double_ | X coordinate. | -| `y` | _double_ | Y coordinate. | +| `sourceName` | _String_ | Source name. | +| `timeOffset` | _int_ | Millisecond offset (positive or negative) to offset the current media position. | **Response Items:** @@ -2013,199 +1897,54 @@ _No additional response items._ --- -### SetSceneItemTransform +### GetMediaState -- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️** -- Added in v4.0.0 +- Unreleased -Set the transform of the specified source item. +Get the current playing state of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| -| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | -| `item` | _String_ | Scene Item name. | -| `x-scale` | _double_ | Width scale factor. | -| `y-scale` | _double_ | Height scale factor. | -| `rotation` | _double_ | Source item rotation (in degrees). | - - -**Response Items:** - -_No additional response items._ - ---- - -### SetSceneItemCrop - -- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️** - -- Added in v4.1.0 - -Sets the crop coordinates of the specified source item. - -**Request Fields:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | -| `item` | _String_ | Scene Item name. | -| `top` | _int_ | Pixel position of the top of the source item. | -| `bottom` | _int_ | Pixel position of the bottom of the source item. | -| `left` | _int_ | Pixel position of the left of the source item. | -| `right` | _int_ | Pixel position of the right of the source item. | - - -**Response Items:** - -_No additional response items._ - ---- - -### DeleteSceneItem - - -- Added in v4.5.0 - -Deletes a scene item. - -**Request Fields:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `scene` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | -| `item` | _Object_ | Scene item to delete (required) | -| `item.name` | _String_ | Scene Item name (prefer `id`, including both is acceptable). | -| `item.id` | _int_ | Scene Item ID. | - - -**Response Items:** - -_No additional response items._ - ---- - -### DuplicateSceneItem - - -- Added in v4.5.0 - -Duplicates a scene item. - -**Request Fields:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `fromScene` | _String (optional)_ | Name of the scene to copy the item from. Defaults to the current scene. | -| `toScene` | _String (optional)_ | Name of the scene to create the item in. Defaults to the current scene. | -| `item` | _Object_ | Scene Item to duplicate from the source scene (required) | -| `item.name` | _String_ | Scene Item name (prefer `id`, including both is acceptable). | -| `item.id` | _int_ | Scene Item ID. | +| `sourceName` | _String_ | Source name. | **Response Items:** | Name | Type | Description | | ---- | :---: | ------------| -| `scene` | _String_ | Name of the scene where the new item was created | -| `item` | _Object_ | New item info | -| `item.id` | _int_ | New item ID | -| `item.name` | _String_ | New item name | +| `mediaState` | _String_ | The media state of the provided source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown` | ---- - -## Scenes - -### SetCurrentScene - - -- Added in v0.3 - -Switch to the specified scene. - -**Request Fields:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `scene-name` | _String_ | Name of the scene to switch to. | - - -**Response Items:** - -_No additional response items._ - ---- - -### GetCurrentScene - - -- Added in v0.3 - -Get the current scene's name and source items. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `name` | _String_ | Name of the currently active scene. | -| `sources` | _Array<SceneItem>_ | Ordered list of the current scene's source items. | - - ---- - -### GetSceneList - - -- Added in v0.3 - -Get a list of scenes in the currently active profile. - -**Request Fields:** - -_No specified parameters._ - -**Response Items:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `current-scene` | _String_ | Name of the currently active scene. | -| `scenes` | _Array<Scene>_ | Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information). | - - ---- - -### ReorderSceneItems - - -- Added in v4.5.0 - -Changes the order of scene items in the requested scene. - -**Request Fields:** - -| Name | Type | Description | -| ---- | :---: | ------------| -| `scene` | _String (optional)_ | Name of the scene to reorder (defaults to current). | -| `items` | _Array<Scene>_ | Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene | -| `items[].id` | _int (optional)_ | Id of a specific scene item. Unique on a scene by scene basis. | -| `items[].name` | _String (optional)_ | Name of a scene item. Sufficiently unique if no scene items share sources within the scene. | - - -**Response Items:** - -_No additional response items._ - --- ## Sources +### GetMediaSourcesList + + +- Unreleased + +List the media state of all media sources (vlc and media source) + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `mediaSources` | _Array<Object>_ | Array of sources | +| `mediaSources.*.sourceName` | _String_ | Unique source name | +| `mediaSources.*.sourceKind` | _String_ | Unique source internal type (a.k.a `ffmpeg_source` or `vlc_source`) | +| `mediaSources.*.mediaState` | _String_ | The current state of media for that source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown` | + + +--- + ### GetSourcesList @@ -2223,7 +1962,7 @@ _No specified parameters._ | ---- | :---: | ------------| | `sources` | _Array<Object>_ | Array of sources | | `sources.*.name` | _String_ | Unique source name | -| `sources.*.typeId` | _String_ | Non-unique source internal type (a.k.a type id) | +| `sources.*.typeId` | _String_ | Non-unique source internal type (a.k.a kind) | | `sources.*.type` | _String_ | Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" | @@ -2266,13 +2005,14 @@ _No specified parameters._ - Added in v4.0.0 -Get the volume of the specified source. +Get the volume of the specified source. Default response uses mul format, NOT SLIDER PERCENTAGE. **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| | `source` | _String_ | Source name. | +| `useDecibel` | _boolean (optional)_ | Output volume in decibels of attenuation instead of amplitude/mul. | **Response Items:** @@ -2280,7 +2020,7 @@ Get the volume of the specified source. | Name | Type | Description | | ---- | :---: | ------------| | `name` | _String_ | Source name. | -| `volume` | _double_ | Volume of the source. Between `0.0` and `1.0`. | +| `volume` | _double_ | Volume of the source. Between `0.0` and `1.0` if using mul, under `0.0` if using dB (since it is attenuating). | | `muted` | _boolean_ | Indicates whether the source is muted. | @@ -2291,14 +2031,15 @@ Get the volume of the specified source. - Added in v4.0.0 -Set the volume of the specified source. +Set the volume of the specified source. Default request format uses mul, NOT SLIDER PERCENTAGE. **Request Fields:** | Name | Type | Description | | ---- | :---: | ------------| | `source` | _String_ | Source name. | -| `volume` | _double_ | Desired volume. Must be between `0.0` and `1.0`. | +| `volume` | _double_ | Desired volume. Must be between `0.0` and `1.0` for mul, and under 0.0 for dB. Note: OBS will interpret dB values under -100.0 as Inf. | +| `useDecibel` | _boolean (optional)_ | Interperet `volume` data as decibels instead of amplitude/mul. | **Response Items:** @@ -2366,6 +2107,52 @@ Inverts the mute status of a specified source. | `source` | _String_ | Source name. | +**Response Items:** + +_No additional response items._ + +--- + +### GetAudioActive + + +- Unreleased + +Get the audio's active status of a specified source. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name. | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `audioActive` | _boolean_ | Audio active status of the source. | + + +--- + +### SetSourceName + + +- Added in v4.8.0 + + + +Note: If the new name already exists as a source, obs-websocket will return an error. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name. | +| `newName` | _String_ | New source name. | + + **Response Items:** _No additional response items._ @@ -2490,8 +2277,8 @@ Get the current properties of a Text GDI Plus source. | ---- | :---: | ------------| | `source` | _String_ | Source name. | | `align` | _String_ | Text Alignment ("left", "center", "right"). | -| `bk-color` | _int_ | Background color. | -| `bk-opacity` | _int_ | Background opacity (0-100). | +| `bk_color` | _int_ | Background color. | +| `bk_opacity` | _int_ | Background opacity (0-100). | | `chatlog` | _boolean_ | Chat log. | | `chatlog_lines` | _int_ | Chat log lines. | | `color` | _int_ | Text color. | @@ -2533,8 +2320,8 @@ Set the current properties of a Text GDI Plus source. | ---- | :---: | ------------| | `source` | _String_ | Name of the source. | | `align` | _String (optional)_ | Text Alignment ("left", "center", "right"). | -| `bk-color` | _int (optional)_ | Background color. | -| `bk-opacity` | _int (optional)_ | Background opacity (0-100). | +| `bk_color` | _int (optional)_ | Background color. | +| `bk_opacity` | _int (optional)_ | Background opacity (0-100). | | `chatlog` | _boolean (optional)_ | Chat log. | | `chatlog_lines` | _int (optional)_ | Chat log lines. | | `color` | _int (optional)_ | Text color. | @@ -2643,7 +2430,7 @@ _No additional response items._ ### GetBrowserSourceProperties -- **⚠️ Deprecated. Since 4.8.0. Prefer the use of GetSourceSettings. ⚠️** +- **⚠️ Deprecated. Since 4.8.0. Prefer the use of GetSourceSettings. Will be removed in v5.0.0 ⚠️** - Added in v4.1.0 @@ -2675,7 +2462,7 @@ Get current properties for a Browser Source. ### SetBrowserSourceProperties -- **⚠️ Deprecated. Since 4.8.0. Prefer the use of SetSourceSettings. ⚠️** +- **⚠️ Deprecated. Since 4.8.0. Prefer the use of SetSourceSettings. Will be removed in v5.0.0 ⚠️** - Added in v4.1.0 @@ -2907,6 +2694,50 @@ Change the visibility/enabled state of a filter | `filterEnabled` | _Boolean_ | New filter state | +**Response Items:** + +_No additional response items._ + +--- + +### GetAudioMonitorType + + +- Added in v4.8.0 + +Get the audio monitoring type of the specified source. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name. | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `monitorType` | _String_ | The monitor type in use. Options: `none`, `monitorOnly`, `monitorAndOutput`. | + + +--- + +### SetAudioMonitorType + + +- Added in v4.8.0 + +Set the audio monitoring type of the specified source. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sourceName` | _String_ | Source name. | +| `monitorType` | _String_ | The monitor type to use. Options: `none`, `monitorOnly`, `monitorAndOutput`. | + + **Response Items:** _No additional response items._ @@ -2929,9 +2760,11 @@ preserved if only one of these two parameters is specified. | Name | Type | Description | | ---- | :---: | ------------| -| `sourceName` | _String_ | Source name. Note that, since scenes are also sources, you can also provide a scene name. | +| `sourceName` | _String (optional)_ | Source name. Note that, since scenes are also sources, you can also provide a scene name. If not provided, the currently active scene is used. | | `embedPictureFormat` | _String (optional)_ | Format of the Data URI encoded picture. Can be "png", "jpg", "jpeg" or "bmp" (or any other value supported by Qt's Image module) | | `saveToFilePath` | _String (optional)_ | Full file path (file extension included) where the captured image is to be saved. Can be in a format different from `pictureFormat`. Can be a relative path. | +| `fileFormat` | _String (optional)_ | Format to save the image file as (one of the values provided in the `supported-image-export-formats` response field of `GetVersion`). If not specified, tries to guess based on file extension. | +| `compressionQuality` | _int (optional)_ | Compression ratio between -1 and 100 to write the image with. -1 is automatic, 1 is smallest file/most compression, 100 is largest file/least compression. Varies with image type. | | `width` | _int (optional)_ | Screenshot width. Defaults to the source's base width. | | `height` | _int (optional)_ | Screenshot height. Defaults to the source's base height. | @@ -2945,6 +2778,969 @@ preserved if only one of these two parameters is specified. | `imageFile` | _String_ | Absolute path to the saved image file (if `saveToFilePath` was specified in the request) | +--- + +## Outputs + +### ListOutputs + + +- Added in v4.7.0 + +List existing outputs + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `outputs` | _Array<Output>_ | Outputs list | + + +--- + +### GetOutputInfo + + +- Added in v4.7.0 + +Get information about a single output + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `outputName` | _String_ | Output name | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `outputInfo` | _Output_ | Output info | + + +--- + +### StartOutput + + +- Added in v4.7.0 + + + +Note: Controlling outputs is an experimental feature of obs-websocket. Some plugins which add outputs to OBS may not function properly when they are controlled in this way. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `outputName` | _String_ | Output name | + + +**Response Items:** + +_No additional response items._ + +--- + +### StopOutput + + +- Added in v4.7.0 + + + +Note: Controlling outputs is an experimental feature of obs-websocket. Some plugins which add outputs to OBS may not function properly when they are controlled in this way. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `outputName` | _String_ | Output name | +| `force` | _boolean (optional)_ | Force stop (default: false) | + + +**Response Items:** + +_No additional response items._ + +--- + +## Profiles + +### SetCurrentProfile + + +- Added in v4.0.0 + +Set the currently active profile. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `profile-name` | _String_ | Name of the desired profile. | + + +**Response Items:** + +_No additional response items._ + +--- + +### GetCurrentProfile + + +- Added in v4.0.0 + +Get the name of the current profile. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `profile-name` | _String_ | Name of the currently active profile. | + + +--- + +### ListProfiles + + +- Added in v4.0.0 + +Get a list of available profiles. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `profiles` | _Array<Object>_ | List of available profiles. | +| `profiles.*.profile-name` | _String_ | Filter name | + + +--- + +## Recording + +### GetRecordingStatus + + +- Unreleased + +Get current recording status. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `isRecording` | _boolean_ | Current recording status. | +| `isRecordingPaused` | _boolean_ | Whether the recording is paused or not. | +| `recordTimecode` | _String (optional)_ | Time elapsed since recording started (only present if currently recording). | + + +--- + +### StartStopRecording + + +- Added in v0.3 + +Toggle recording on or off (depending on the current recording state). + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### StartRecording + + +- Added in v4.1.0 + +Start recording. +Will return an `error` if recording is already active. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### StopRecording + + +- Added in v4.1.0 + +Stop recording. +Will return an `error` if recording is not active. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### PauseRecording + + +- Added in v4.7.0 + +Pause the current recording. +Returns an error if recording is not active or already paused. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### ResumeRecording + + +- Added in v4.7.0 + +Resume/unpause the current recording (if paused). +Returns an error if recording is not active or not paused. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### SetRecordingFolder + + +- Added in v4.1.0 + + + +Please note: if `SetRecordingFolder` is called while a recording is +in progress, the change won't be applied immediately and will be +effective on the next recording. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `rec-folder` | _String_ | Path of the recording folder. | + + +**Response Items:** + +_No additional response items._ + +--- + +### GetRecordingFolder + + +- Added in v4.1.0 + +Get the path of the current recording folder. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `rec-folder` | _String_ | Path of the recording folder. | + + +--- + +## Replay Buffer + +### GetReplayBufferStatus + + +- Unreleased + +Get the status of the OBS replay buffer. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `isReplayBufferActive` | _boolean_ | Current recording status. | + + +--- + +### StartStopReplayBuffer + + +- Added in v4.2.0 + +Toggle the Replay Buffer on/off (depending on the current state of the replay buffer). + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### StartReplayBuffer + + +- Added in v4.2.0 + +Start recording into the Replay Buffer. +Will return an `error` if the Replay Buffer is already active or if the +"Save Replay Buffer" hotkey is not set in OBS' settings. +Setting this hotkey is mandatory, even when triggering saves only +through obs-websocket. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### StopReplayBuffer + + +- Added in v4.2.0 + +Stop recording into the Replay Buffer. +Will return an `error` if the Replay Buffer is not active. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +### SaveReplayBuffer + + +- Added in v4.2.0 + +Flush and save the contents of the Replay Buffer to disk. This is +basically the same as triggering the "Save Replay Buffer" hotkey. +Will return an `error` if the Replay Buffer is not active. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +_No additional response items._ + +--- + +## Scene Collections + +### SetCurrentSceneCollection + + +- Added in v4.0.0 + +Change the active scene collection. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sc-name` | _String_ | Name of the desired scene collection. | + + +**Response Items:** + +_No additional response items._ + +--- + +### GetCurrentSceneCollection + + +- Added in v4.0.0 + +Get the name of the current scene collection. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sc-name` | _String_ | Name of the currently active scene collection. | + + +--- + +### ListSceneCollections + + +- Added in v4.0.0 + +List available scene collections + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-collections` | _Array<String>_ | Scene collections list | +| `scene-collections.*.sc-name` | _String_ | Scene collection name | + + +--- + +## Scene Items + +### GetSceneItemList + + +- Unreleased + +Get a list of all scene items in a scene. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sceneName` | _String (optional)_ | Name of the scene to get the list of scene items from. Defaults to the current scene if not specified. | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sceneName` | _String_ | Name of the requested (or current) scene | +| `sceneItems` | _Array<Object>_ | Array of scene items | +| `sceneItems.*.itemId` | _int_ | Unique item id of the source item | +| `sceneItems.*.sourceKind` | _String_ | ID if the scene item's source. For example `vlc_source` or `image_source` | +| `sceneItems.*.sourceName` | _String_ | Name of the scene item's source | +| `sceneItems.*.sourceType` | _String_ | Type of the scene item's source. Either `input`, `group`, or `scene` | + + +--- + +### GetSceneItemProperties + + +- Added in v4.3.0 + +Gets the scene specific properties of the specified source item. +Coordinates are relative to the item's parent (the scene or group it belongs to). + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | +| `item` | _String \| Object_ | Scene Item name (if this field is a string) or specification (if it is an object). | +| `item.name` | _String (optional)_ | Scene Item name (if the `item` field is an object) | +| `item.id` | _int (optional)_ | Scene Item ID (if the `item` field is an object) | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `name` | _String_ | Scene Item name. | +| `itemId` | _int_ | Scene Item ID. | +| `position.x` | _double_ | The x position of the source from the left. | +| `position.y` | _double_ | The y position of the source from the top. | +| `position.alignment` | _int_ | The point on the source that the item is manipulated from. | +| `rotation` | _double_ | The clockwise rotation of the item in degrees around the point of alignment. | +| `scale.x` | _double_ | The x-scale factor of the source. | +| `scale.y` | _double_ | The y-scale factor of the source. | +| `crop.top` | _int_ | The number of pixels cropped off the top of the source before scaling. | +| `crop.right` | _int_ | The number of pixels cropped off the right of the source before scaling. | +| `crop.bottom` | _int_ | The number of pixels cropped off the bottom of the source before scaling. | +| `crop.left` | _int_ | The number of pixels cropped off the left of the source before scaling. | +| `visible` | _bool_ | If the source is visible. | +| `muted` | _bool_ | If the source is muted. | +| `locked` | _bool_ | If the source's transform is locked. | +| `bounds.type` | _String_ | Type of bounding box. Can be "OBS_BOUNDS_STRETCH", "OBS_BOUNDS_SCALE_INNER", "OBS_BOUNDS_SCALE_OUTER", "OBS_BOUNDS_SCALE_TO_WIDTH", "OBS_BOUNDS_SCALE_TO_HEIGHT", "OBS_BOUNDS_MAX_ONLY" or "OBS_BOUNDS_NONE". | +| `bounds.alignment` | _int_ | Alignment of the bounding box. | +| `bounds.x` | _double_ | Width of the bounding box. | +| `bounds.y` | _double_ | Height of the bounding box. | +| `sourceWidth` | _int_ | Base width (without scaling) of the source | +| `sourceHeight` | _int_ | Base source (without scaling) of the source | +| `width` | _double_ | Scene item width (base source width multiplied by the horizontal scaling factor) | +| `height` | _double_ | Scene item height (base source height multiplied by the vertical scaling factor) | +| `alignment` | _int_ | The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis. | +| `parentGroupName` | _String (optional)_ | Name of the item's parent (if this item belongs to a group) | +| `groupChildren` | _Array<SceneItemTransform> (optional)_ | List of children (if this item is a group) | + + +--- + +### SetSceneItemProperties + + +- Added in v4.3.0 + +Sets the scene specific properties of a source. Unspecified properties will remain unchanged. +Coordinates are relative to the item's parent (the scene or group it belongs to). + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String (optional)_ | Name of the scene the source item belongs to. Defaults to the current scene. | +| `item` | _String \| Object_ | Scene Item name (if this field is a string) or specification (if it is an object). | +| `item.name` | _String (optional)_ | Scene Item name (if the `item` field is an object) | +| `item.id` | _int (optional)_ | Scene Item ID (if the `item` field is an object) | +| `position.x` | _double (optional)_ | The new x position of the source. | +| `position.y` | _double (optional)_ | The new y position of the source. | +| `position.alignment` | _int (optional)_ | The new alignment of the source. | +| `rotation` | _double (optional)_ | The new clockwise rotation of the item in degrees. | +| `scale.x` | _double (optional)_ | The new x scale of the item. | +| `scale.y` | _double (optional)_ | The new y scale of the item. | +| `crop.top` | _int (optional)_ | The new amount of pixels cropped off the top of the source before scaling. | +| `crop.bottom` | _int (optional)_ | The new amount of pixels cropped off the bottom of the source before scaling. | +| `crop.left` | _int (optional)_ | The new amount of pixels cropped off the left of the source before scaling. | +| `crop.right` | _int (optional)_ | The new amount of pixels cropped off the right of the source before scaling. | +| `visible` | _bool (optional)_ | The new visibility of the source. 'true' shows source, 'false' hides source. | +| `locked` | _bool (optional)_ | The new locked status of the source. 'true' keeps it in its current position, 'false' allows movement. | +| `bounds.type` | _String (optional)_ | The new bounds type of the source. Can be "OBS_BOUNDS_STRETCH", "OBS_BOUNDS_SCALE_INNER", "OBS_BOUNDS_SCALE_OUTER", "OBS_BOUNDS_SCALE_TO_WIDTH", "OBS_BOUNDS_SCALE_TO_HEIGHT", "OBS_BOUNDS_MAX_ONLY" or "OBS_BOUNDS_NONE". | +| `bounds.alignment` | _int (optional)_ | The new alignment of the bounding box. (0-2, 4-6, 8-10) | +| `bounds.x` | _double (optional)_ | The new width of the bounding box. | +| `bounds.y` | _double (optional)_ | The new height of the bounding box. | + + +**Response Items:** + +_No additional response items._ + +--- + +### ResetSceneItem + + +- Added in v4.2.0 + +Reset a scene item. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | +| `item` | _String \| Object_ | Scene Item name (if this field is a string) or specification (if it is an object). | +| `item.name` | _String (optional)_ | Scene Item name (if the `item` field is an object) | +| `item.id` | _int (optional)_ | Scene Item ID (if the `item` field is an object) | + + +**Response Items:** + +_No additional response items._ + +--- + +### SetSceneItemRender + + +- Added in v0.3 + +Show or hide a specified source item in a specified scene. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the currently active scene. | +| `source` | _String_ | Scene Item name. | +| `render` | _boolean_ | true = shown ; false = hidden | + + +**Response Items:** + +_No additional response items._ + +--- + +### SetSceneItemPosition + +- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️** + +- Added in v4.0.0 + +Sets the coordinates of a specified source item. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | +| `item` | _String_ | Scene Item name. | +| `x` | _double_ | X coordinate. | +| `y` | _double_ | Y coordinate. | + + +**Response Items:** + +_No additional response items._ + +--- + +### SetSceneItemTransform + +- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️** + +- Added in v4.0.0 + +Set the transform of the specified source item. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | +| `item` | _String_ | Scene Item name. | +| `x-scale` | _double_ | Width scale factor. | +| `y-scale` | _double_ | Height scale factor. | +| `rotation` | _double_ | Source item rotation (in degrees). | + + +**Response Items:** + +_No additional response items._ + +--- + +### SetSceneItemCrop + +- **⚠️ Deprecated. Since 4.3.0. Prefer the use of SetSceneItemProperties. ⚠️** + +- Added in v4.1.0 + +Sets the crop coordinates of the specified source item. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | +| `item` | _String_ | Scene Item name. | +| `top` | _int_ | Pixel position of the top of the source item. | +| `bottom` | _int_ | Pixel position of the bottom of the source item. | +| `left` | _int_ | Pixel position of the left of the source item. | +| `right` | _int_ | Pixel position of the right of the source item. | + + +**Response Items:** + +_No additional response items._ + +--- + +### DeleteSceneItem + + +- Added in v4.5.0 + +Deletes a scene item. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene` | _String (optional)_ | Name of the scene the scene item belongs to. Defaults to the current scene. | +| `item` | _Object_ | Scene item to delete (required) | +| `item.name` | _String_ | Scene Item name (prefer `id`, including both is acceptable). | +| `item.id` | _int_ | Scene Item ID. | + + +**Response Items:** + +_No additional response items._ + +--- + +### AddSceneItem + + +- Unreleased + +Creates a scene item in a scene. In other words, this is how you add a source into a scene. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sceneName` | _String_ | Name of the scene to create the scene item in | +| `sourceName` | _String_ | Name of the source to be added | +| `setVisible` | _boolean_ | Whether to make the sceneitem visible on creation or not. Default `true` | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `itemId` | _int_ | Numerical ID of the created scene item | + + +--- + +### DuplicateSceneItem + + +- Added in v4.5.0 + +Duplicates a scene item. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `fromScene` | _String (optional)_ | Name of the scene to copy the item from. Defaults to the current scene. | +| `toScene` | _String (optional)_ | Name of the scene to create the item in. Defaults to the current scene. | +| `item` | _Object_ | Scene Item to duplicate from the source scene (required) | +| `item.name` | _String_ | Scene Item name (prefer `id`, including both is acceptable). | +| `item.id` | _int_ | Scene Item ID. | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene` | _String_ | Name of the scene where the new item was created | +| `item` | _Object_ | New item info | +| `item.id` | _int_ | New item ID | +| `item.name` | _String_ | New item name | + + +--- + +## Scenes + +### SetCurrentScene + + +- Added in v0.3 + +Switch to the specified scene. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene-name` | _String_ | Name of the scene to switch to. | + + +**Response Items:** + +_No additional response items._ + +--- + +### GetCurrentScene + + +- Added in v0.3 + +Get the current scene's name and source items. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `name` | _String_ | Name of the currently active scene. | +| `sources` | _Array<SceneItem>_ | Ordered list of the current scene's source items. | + + +--- + +### GetSceneList + + +- Added in v0.3 + +Get a list of scenes in the currently active profile. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `current-scene` | _String_ | Name of the currently active scene. | +| `scenes` | _Array<Scene>_ | Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information). | + + +--- + +### CreateScene + + +- Added in v4.8.0 + +Create a new scene scene. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sceneName` | _String_ | Name of the scene to create. | + + +**Response Items:** + +_No additional response items._ + +--- + +### ReorderSceneItems + + +- Added in v4.5.0 + +Changes the order of scene items in the requested scene. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `scene` | _String (optional)_ | Name of the scene to reorder (defaults to current). | +| `items` | _Array<Scene>_ | Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene | +| `items.*.id` | _int (optional)_ | Id of a specific scene item. Unique on a scene by scene basis. | +| `items.*.name` | _String (optional)_ | Name of a scene item. Sufficiently unique if no scene items share sources within the scene. | + + +**Response Items:** + +_No additional response items._ + +--- + +### SetSceneTransitionOverride + + +- Added in v4.8.0 + +Set a scene to use a specific transition override. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sceneName` | _String_ | Name of the scene to switch to. | +| `transitionName` | _String_ | Name of the transition to use. | +| `transitionDuration` | _int (Optional)_ | Duration in milliseconds of the transition if transition is not fixed. Defaults to the current duration specified in the UI if there is no current override and this value is not given. | + + +**Response Items:** + +_No additional response items._ + +--- + +### RemoveSceneTransitionOverride + + +- Added in v4.8.0 + +Remove any transition override on a scene. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sceneName` | _String_ | Name of the scene to switch to. | + + +**Response Items:** + +_No additional response items._ + +--- + +### GetSceneTransitionOverride + + +- Added in v4.8.0 + +Get the current scene transition override. + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `sceneName` | _String_ | Name of the scene to switch to. | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `transitionName` | _String_ | Name of the current overriding transition. Empty string if no override is set. | +| `transitionDuration` | _int_ | Transition duration. `-1` if no override is set. | + + --- ## Streaming @@ -2978,7 +3774,7 @@ _No specified parameters._ - Added in v0.3 -Toggle streaming on or off. +Toggle streaming on or off (depending on the current stream state). **Request Fields:** @@ -3113,7 +3909,6 @@ _No additional response items._ - Added in v4.6.0 Send the provided text as embedded CEA-608 caption data. -As of OBS Studio 23.1, captions are not yet available on Linux. **Request Fields:** @@ -3255,7 +4050,7 @@ _No additional response items._ - Added in v4.1.0 -Toggles Studio Mode. +Toggles Studio Mode (depending on the current state of studio mode). **Request Fields:** @@ -3372,3 +4167,70 @@ _No specified parameters._ --- +### GetTransitionPosition + + +- Added in v4.8.0 + +Get the position of the current transition. + +**Request Fields:** + +_No specified parameters._ + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `position` | _double_ | current transition position. This value will be between 0.0 and 1.0. Note: Transition returns 1.0 when not active. | + + +--- + +### GetTransitionSettings + + +- Unreleased + +Get the current settings of a transition + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `transitionName` | _String_ | Transition name | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `transitionSettings` | _Object_ | Current transition settings | + + +--- + +### SetTransitionSettings + + +- Unreleased + +Change the current settings of a transition + +**Request Fields:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `transitionName` | _String_ | Transition name | +| `transitionSettings` | _Object_ | Transition settings (they can be partial) | + + +**Response Items:** + +| Name | Type | Description | +| ---- | :---: | ------------| +| `transitionSettings` | _Object_ | Updated transition settings | + + +--- + diff --git a/docs/partials/introduction.md b/docs/partials/introduction.md index c8de4503..496363e7 100644 --- a/docs/partials/introduction.md +++ b/docs/partials/introduction.md @@ -1,8 +1,8 @@ -# obs-websocket 4.7.0 protocol reference +# obs-websocket 4.8.0 protocol reference # General Introduction Messages are exchanged between the client and the server as JSON objects. -This protocol is based on the original OBS Remote protocol created by Bill Hamilton, with new commands specific to OBS Studio. +This protocol is based on the original OBS Remote protocol created by Bill Hamilton, with new commands specific to OBS Studio. As of v5.0.0, backwards compatability with the protocol will not be kept. # Authentication `obs-websocket` uses SHA256 to transmit credentials. @@ -32,3 +32,5 @@ auth_response_string = secret + challenge auth_response_hash = binary_sha256(auth_response_string) auth_response = base64_encode(auth_response_hash) ``` + +You can also refer to any of the client libraries listed on the [README](README.md) for examples of how to authenticate. diff --git a/docs/partials/requestsHeader.md b/docs/partials/requestsHeader.md index 457ad61b..b73efc0c 100644 --- a/docs/partials/requestsHeader.md +++ b/docs/partials/requestsHeader.md @@ -6,6 +6,6 @@ Requests are sent by the client and require at least the following two fields: Once a request is sent, the server will return a JSON response with at least the following fields: - `message-id` _String_: The client defined identifier specified in the request. - `status` _String_: Response status, will be one of the following: `ok`, `error` -- `error` _String_: An error message accompanying an `error` status. +- `error` _String (Optional)_: An error message accompanying an `error` status. Additional information may be required/returned depending on the request type. See below for more information. diff --git a/installer/installer.iss b/installer/installer.iss index 243f3a31..e94ff579 100644 --- a/installer/installer.iss +++ b/installer/installer.iss @@ -23,6 +23,7 @@ DefaultGroupName={#MyAppName} OutputBaseFilename=obs-websocket-Windows-Installer Compression=lzma SolidCompression=yes +DirExistsWarning=no [Languages] Name: "english"; MessagesFile: "compiler:Default.isl" diff --git a/src/Config.cpp b/src/Config.cpp index 4ed30608..1a17065f 100644 --- a/src/Config.cpp +++ b/src/Config.cpp @@ -25,6 +25,7 @@ with this program. If not, see #define SECTION_NAME "WebsocketAPI" #define PARAM_ENABLE "ServerEnabled" #define PARAM_PORT "ServerPort" +#define PARAM_LOCKTOIPV4 "LockToIPv4" #define PARAM_DEBUG "DebugEnabled" #define PARAM_ALERT "AlertsEnabled" #define PARAM_AUTHREQUIRED "AuthRequired" @@ -41,6 +42,7 @@ with this program. If not, see Config::Config() : ServerEnabled(true), ServerPort(4444), + LockToIPv4(false), DebugEnabled(false), AlertsEnabled(true), AuthRequired(false), @@ -67,6 +69,7 @@ void Config::Load() ServerEnabled = config_get_bool(obsConfig, SECTION_NAME, PARAM_ENABLE); ServerPort = config_get_uint(obsConfig, SECTION_NAME, PARAM_PORT); + LockToIPv4 = config_get_bool(obsConfig, SECTION_NAME, PARAM_LOCKTOIPV4); DebugEnabled = config_get_bool(obsConfig, SECTION_NAME, PARAM_DEBUG); AlertsEnabled = config_get_bool(obsConfig, SECTION_NAME, PARAM_ALERT); @@ -82,6 +85,7 @@ void Config::Save() config_set_bool(obsConfig, SECTION_NAME, PARAM_ENABLE, ServerEnabled); config_set_uint(obsConfig, SECTION_NAME, PARAM_PORT, ServerPort); + config_set_bool(obsConfig, SECTION_NAME, PARAM_LOCKTOIPV4, LockToIPv4); config_set_bool(obsConfig, SECTION_NAME, PARAM_DEBUG, DebugEnabled); config_set_bool(obsConfig, SECTION_NAME, PARAM_ALERT, AlertsEnabled); @@ -104,6 +108,8 @@ void Config::SetDefaults() SECTION_NAME, PARAM_ENABLE, ServerEnabled); config_set_default_uint(obsConfig, SECTION_NAME, PARAM_PORT, ServerPort); + config_set_default_bool(obsConfig, + SECTION_NAME, PARAM_LOCKTOIPV4, LockToIPv4); config_set_default_bool(obsConfig, SECTION_NAME, PARAM_DEBUG, DebugEnabled); @@ -205,16 +211,17 @@ void Config::OnFrontendEvent(enum obs_frontend_event event, void* param) bool previousEnabled = config->ServerEnabled; uint64_t previousPort = config->ServerPort; + bool previousLock = config->LockToIPv4; config->SetDefaults(); config->Load(); - if (config->ServerEnabled != previousEnabled || config->ServerPort != previousPort) { + if (config->ServerEnabled != previousEnabled || config->ServerPort != previousPort || config->LockToIPv4 != previousLock) { auto server = GetServer(); server->stop(); if (config->ServerEnabled) { - server->start(config->ServerPort); + server->start(config->ServerPort, config->LockToIPv4); if (previousEnabled != config->ServerEnabled) { Utils::SysTrayNotify(startMessage, QSystemTrayIcon::MessageIcon::Information); @@ -246,6 +253,13 @@ void Config::MigrateFromGlobalSettings() config_remove_value(source, SECTION_NAME, PARAM_PORT); } + + if(config_has_user_value(source, SECTION_NAME, PARAM_LOCKTOIPV4)) { + bool value = config_get_bool(source, SECTION_NAME, PARAM_LOCKTOIPV4); + config_set_bool(destination, SECTION_NAME, PARAM_LOCKTOIPV4, value); + + config_remove_value(source, SECTION_NAME, PARAM_LOCKTOIPV4); + } if(config_has_user_value(source, SECTION_NAME, PARAM_DEBUG)) { bool value = config_get_bool(source, SECTION_NAME, PARAM_DEBUG); diff --git a/src/Config.h b/src/Config.h index 0845f874..f21e396a 100644 --- a/src/Config.h +++ b/src/Config.h @@ -42,6 +42,7 @@ class Config { bool ServerEnabled; uint64_t ServerPort; + bool LockToIPv4; bool DebugEnabled; bool AlertsEnabled; diff --git a/src/Utils.cpp b/src/Utils.cpp index dd5ad14a..11c55e9c 100644 --- a/src/Utils.cpp +++ b/src/Utils.cpp @@ -51,6 +51,25 @@ obs_bounds_type getBoundsTypeFromName(QString name) { return boundTypeNames.key(name); } +bool Utils::StringInStringList(char** strings, const char* string) { + if (!strings) { + return false; + } + + size_t index = 0; + while (strings[index] != NULL) { + char* value = strings[index]; + + if (strcmp(value, string) == 0) { + return true; + } + + index++; + } + + return false; +} + obs_data_array_t* Utils::StringListToArray(char** strings, const char* key) { obs_data_array_t* list = obs_data_array_create(); @@ -485,11 +504,8 @@ QString Utils::OBSVersionString() { } QSystemTrayIcon* Utils::GetTrayIcon() { - QMainWindow* main = (QMainWindow*)obs_frontend_get_main_window(); - if (!main) return nullptr; - - QList trays = main->findChildren(); - return trays.isEmpty() ? nullptr : trays.first(); + void* systemTray = obs_frontend_get_system_tray(); + return reinterpret_cast(systemTray); } void Utils::SysTrayNotify(QString text, @@ -684,8 +700,8 @@ bool Utils::SetFilenameFormatting(const char* filenameFormatting) { /** * @typedef {Object} `SceneItemTransform` - * @property {int} `position.x` The x position of the scene item from the left. - * @property {int} `position.y` The y position of the scene item from the top. + * @property {double} `position.x` The x position of the scene item from the left. + * @property {double} `position.y` The y position of the scene item from the top. * @property {int} `position.alignment` The point on the scene item that the item is manipulated from. * @property {double} `rotation` The clockwise rotation of the scene item in degrees around the point of alignment. * @property {double} `scale.x` The x-scale factor of the scene item. diff --git a/src/Utils.h b/src/Utils.h index dbe2481f..69b86fc5 100644 --- a/src/Utils.h +++ b/src/Utils.h @@ -35,6 +35,7 @@ typedef void(*PauseRecordingFunction)(bool); typedef bool(*RecordingPausedFunction)(); namespace Utils { + bool StringInStringList(char** strings, const char* string); obs_data_array_t* StringListToArray(char** strings, const char* key); obs_data_array_t* GetSceneItems(obs_source_t* source); obs_data_t* GetSceneItemData(obs_sceneitem_t* item); diff --git a/src/WSEvents.cpp b/src/WSEvents.cpp index 37ada8ee..56d24c8a 100644 --- a/src/WSEvents.cpp +++ b/src/WSEvents.cpp @@ -271,10 +271,21 @@ void WSEvents::connectSourceSignals(obs_source_t* source) { signal_handler_connect(sh, "volume", OnSourceVolumeChange, this); signal_handler_connect(sh, "audio_sync", OnSourceAudioSyncOffsetChanged, this); signal_handler_connect(sh, "audio_mixers", OnSourceAudioMixersChanged, this); + signal_handler_connect(sh, "audio_activate", OnSourceAudioActivated, this); + signal_handler_connect(sh, "audio_deactivate", OnSourceAudioDeactivated, this); signal_handler_connect(sh, "filter_add", OnSourceFilterAdded, this); signal_handler_connect(sh, "filter_remove", OnSourceFilterRemoved, this); signal_handler_connect(sh, "reorder_filters", OnSourceFilterOrderChanged, this); + + signal_handler_connect(sh, "media_play", OnMediaPlaying, this); + signal_handler_connect(sh, "media_pause", OnMediaPaused, this); + signal_handler_connect(sh, "media_restart", OnMediaRestarted, this); + signal_handler_connect(sh, "media_stopped", OnMediaStopped, this); + signal_handler_connect(sh, "media_next", OnMediaNext, this); + signal_handler_connect(sh, "media_previous", OnMediaPrevious, this); + signal_handler_connect(sh, "media_started", OnMediaStarted, this); + signal_handler_connect(sh, "media_ended", OnMediaEnded, this); if (sourceType == OBS_SOURCE_TYPE_SCENE) { signal_handler_connect(sh, "reorder", OnSceneReordered, this); @@ -303,6 +314,8 @@ void WSEvents::disconnectSourceSignals(obs_source_t* source) { signal_handler_disconnect(sh, "volume", OnSourceVolumeChange, this); signal_handler_disconnect(sh, "audio_sync", OnSourceAudioSyncOffsetChanged, this); signal_handler_disconnect(sh, "audio_mixers", OnSourceAudioMixersChanged, this); + signal_handler_disconnect(sh, "audio_activate", OnSourceAudioActivated, this); + signal_handler_disconnect(sh, "audio_deactivate", OnSourceAudioDeactivated, this); signal_handler_disconnect(sh, "filter_add", OnSourceFilterAdded, this); signal_handler_disconnect(sh, "filter_remove", OnSourceFilterRemoved, this); @@ -322,6 +335,15 @@ void WSEvents::disconnectSourceSignals(obs_source_t* source) { signal_handler_disconnect(sh, "transition_start", OnTransitionBegin, this); signal_handler_disconnect(sh, "transition_stop", OnTransitionEnd, this); signal_handler_disconnect(sh, "transition_video_stop", OnTransitionVideoEnd, this); + + signal_handler_disconnect(sh, "media_play", OnMediaPlaying, this); + signal_handler_disconnect(sh, "media_pause", OnMediaPaused, this); + signal_handler_disconnect(sh, "media_restart", OnMediaRestarted, this); + signal_handler_disconnect(sh, "media_stopped", OnMediaStopped, this); + signal_handler_disconnect(sh, "media_next", OnMediaNext, this); + signal_handler_disconnect(sh, "media_previous", OnMediaPrevious, this); + signal_handler_disconnect(sh, "media_started", OnMediaStarted, this); + signal_handler_disconnect(sh, "media_ended", OnMediaEnded, this); } void WSEvents::connectFilterSignals(obs_source_t* filter) { @@ -348,7 +370,7 @@ void WSEvents::hookTransitionPlaybackEvents() { obs_frontend_source_list transitions = {}; obs_frontend_get_transitions(&transitions); - for (int i = 0; i < transitions.sources.num; i++) { + for (uint i = 0; i < transitions.sources.num; i++) { obs_source_t* transition = transitions.sources.array[i]; signal_handler_t* sh = obs_source_get_signal_handler(transition); signal_handler_disconnect(sh, "transition_start", OnTransitionBegin, this); @@ -366,7 +388,7 @@ void WSEvents::unhookTransitionPlaybackEvents() { obs_frontend_source_list transitions = {}; obs_frontend_get_transitions(&transitions); - for (int i = 0; i < transitions.sources.num; i++) { + for (uint i = 0; i < transitions.sources.num; i++) { obs_source_t* transition = transitions.sources.array[i]; signal_handler_t* sh = obs_source_get_signal_handler(transition); signal_handler_disconnect(sh, "transition_start", OnTransitionBegin, this); @@ -407,6 +429,16 @@ QString WSEvents::getRecordingTimecode() { return Utils::nsToTimestamp(getRecordingTime()); } +OBSDataAutoRelease getMediaSourceData(calldata_t* data) { + OBSDataAutoRelease fields = obs_data_create(); + OBSSource source = calldata_get_pointer(data, "source"); + + obs_data_set_string(fields, "sourceName", obs_source_get_name(source)); + obs_data_set_string(fields, "sourceKind", obs_source_get_id(source)); + + return fields; +} + /** * Indicates a scene change. * @@ -433,6 +465,8 @@ void WSEvents::OnSceneChange() { * The scene list has been modified. * Scenes have been added, removed, or renamed. * + * Note: This event is not fired when the scenes are reordered. + * * @api events * @name ScenesChanged * @category scenes @@ -724,7 +758,7 @@ void WSEvents::OnExit() { } /** - * Emit every 2 seconds. + * Emitted every 2 seconds when stream is active. * * @return {boolean} `streaming` Current streaming state. * @return {boolean} `recording` Current recording state. @@ -831,6 +865,7 @@ void WSEvents::StreamStatus() { * @api events * @name Heartbeat * @category general + * @since v0.3 */ void WSEvents::Heartbeat() { @@ -1098,6 +1133,52 @@ void WSEvents::OnSourceMuteStateChange(void* param, calldata_t* data) { self->broadcastUpdate("SourceMuteStateChanged", fields); } +/** + * A source has removed audio. + * + * @return {String} `sourceName` Source name + * + * @api events + * @name SourceAudioDeactivated + * @category sources + * @since unreleased + */ +void WSEvents::OnSourceAudioDeactivated(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSSource source = calldata_get_pointer(data, "source"); + if (!source) { + return; + } + + OBSDataAutoRelease fields = obs_data_create(); + obs_data_set_string(fields, "sourceName", obs_source_get_name(source)); + self->broadcastUpdate("SourceAudioDeactivated", fields); +} + +/** + * A source has added audio. + * + * @return {String} `sourceName` Source name + * + * @api events + * @name SourceAudioActivated + * @category sources + * @since unreleased + */ +void WSEvents::OnSourceAudioActivated(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSSource source = calldata_get_pointer(data, "source"); + if (!source) { + return; + } + + OBSDataAutoRelease fields = obs_data_create(); + obs_data_set_string(fields, "sourceName", obs_source_get_name(source)); + self->broadcastUpdate("SourceAudioActivated", fields); +} + /** * The audio sync offset of a source has changed. * @@ -1177,6 +1258,7 @@ void WSEvents::OnSourceAudioMixersChanged(void* param, calldata_t* data) { * * @return {String} `previousName` Previous source name * @return {String} `newName` New source name + * @return {String} `sourceType` Type of source (input, scene, filter, transition) * * @api events * @name SourceRenamed @@ -1201,6 +1283,8 @@ void WSEvents::OnSourceRename(void* param, calldata_t* data) { OBSDataAutoRelease fields = obs_data_create(); obs_data_set_string(fields, "previousName", previousName); obs_data_set_string(fields, "newName", newName); + obs_data_set_string(fields, "sourceType", + sourceTypeToString(obs_source_get_type(source))); // TODO: Split into dedicated events for source/scene. Only doing it this way for backwards compatability until 5.0 self->broadcastUpdate("SourceRenamed", fields); } @@ -1313,6 +1397,7 @@ void WSEvents::OnSourceFilterVisibilityChanged(void* param, calldata_t* data) { * @return {Array} `filters` Ordered Filters list * @return {String} `filters.*.name` Filter name * @return {String} `filters.*.type` Filter type + * @return {boolean} `filters.*.enabled` Filter visibility status * * @api events * @name SourceFiltersReordered @@ -1336,7 +1421,175 @@ void WSEvents::OnSourceFilterOrderChanged(void* param, calldata_t* data) { } /** - * Scene items have been reordered. + * A media source has started playing. + * + * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaPlaying + * @category media + * @since unreleased + */ +void WSEvents::OnMediaPlaying(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaPlaying", fields); +} + +/** + * A media source has been paused. + * + * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaPaused + * @category media + * @since unreleased + */ +void WSEvents::OnMediaPaused(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaPaused", fields); +} + +/** + * A media source has been restarted. + * + * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaRestarted + * @category media + * @since unreleased + */ +void WSEvents::OnMediaRestarted(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaRestarted", fields); +} + +/** + * A media source has been stopped. + * + * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaStopped + * @category media + * @since unreleased + */ +void WSEvents::OnMediaStopped(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaStopped", fields); +} + +/** + * A media source has gone to the next item in the playlist. + * + * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaNext + * @category media + * @since unreleased + */ +void WSEvents::OnMediaNext(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaNext", fields); +} + +/** + * A media source has gone to the previous item in the playlist. + * + * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaPrevious + * @category media + * @since unreleased + */ +void WSEvents::OnMediaPrevious(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaPrevious", fields); +} + +/** + * A media source has been started. + * + * Note: These events are emitted by the OBS sources themselves. For example when the media file starts playing. The behavior depends on the type of media source being used. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaStarted + * @category media + * @since unreleased + */ +void WSEvents::OnMediaStarted(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaStarted", fields); +} + +/** + * A media source has ended. + * + * Note: These events are emitted by the OBS sources themselves. For example when the media file ends. The behavior depends on the type of media source being used. + * + * @return {String} `sourceName` Source name + * @return {String} `sourceKind` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`) + * + * @api events + * @name MediaEnded + * @category media + * @since unreleased + */ +void WSEvents::OnMediaEnded(void* param, calldata_t* data) { + auto self = reinterpret_cast(param); + + OBSDataAutoRelease fields = getMediaSourceData(data); + + self->broadcastUpdate("MediaEnded", fields); +} + +/** + * Scene items within a scene have been reordered. * * @return {String} `scene-name` Name of the scene where items have been reordered. * @return {Array} `scene-items` Ordered list of scene items @@ -1379,7 +1632,7 @@ void WSEvents::OnSceneReordered(void* param, calldata_t* data) { } /** - * An item has been added to the current scene. + * A scene item has been added to a scene. * * @return {String} `scene-name` Name of the scene. * @return {String} `item-name` Name of the item added to the scene. @@ -1412,7 +1665,7 @@ void WSEvents::OnSceneItemAdd(void* param, calldata_t* data) { } /** - * An item has been removed from the current scene. + * A scene item has been removed from a scene. * * @return {String} `scene-name` Name of the scene. * @return {String} `item-name` Name of the item removed from the scene. @@ -1445,7 +1698,7 @@ void WSEvents::OnSceneItemDelete(void* param, calldata_t* data) { } /** - * An item's visibility has been toggled. + * A scene item's visibility has been toggled. * * @return {String} `scene-name` Name of the scene. * @return {String} `item-name` Name of the item in the scene. @@ -1483,7 +1736,7 @@ void WSEvents::OnSceneItemVisibilityChanged(void* param, calldata_t* data) { } /** - * An item's locked status has been toggled. + * A scene item's locked status has been toggled. * * @return {String} `scene-name` Name of the scene. * @return {String} `item-name` Name of the item in the scene. @@ -1521,7 +1774,7 @@ void WSEvents::OnSceneItemLockChanged(void* param, calldata_t* data) { } /** - * An item's transform has been changed. + * A scene item's transform has been changed. * * @return {String} `scene-name` Name of the scene. * @return {String} `item-name` Name of the item in the scene. @@ -1672,7 +1925,7 @@ void WSEvents::OnStudioModeSwitched(bool checked) { } /** - * A custom broadcast message was received + * A custom broadcast message, sent by the server, requested by one of the websocket clients. * * @return {String} `realm` Identifier provided by the sender * @return {Object} `data` User-defined data diff --git a/src/WSEvents.h b/src/WSEvents.h index 06ce7f2c..dc814e83 100644 --- a/src/WSEvents.h +++ b/src/WSEvents.h @@ -126,6 +126,8 @@ private: static void OnSourceMuteStateChange(void* param, calldata_t* data); static void OnSourceAudioSyncOffsetChanged(void* param, calldata_t* data); static void OnSourceAudioMixersChanged(void* param, calldata_t* data); + static void OnSourceAudioActivated(void* param, calldata_t* data); + static void OnSourceAudioDeactivated(void* param, calldata_t* data); static void OnSourceRename(void* param, calldata_t* data); @@ -133,6 +135,15 @@ private: static void OnSourceFilterRemoved(void* param, calldata_t* data); static void OnSourceFilterVisibilityChanged(void* param, calldata_t* data); static void OnSourceFilterOrderChanged(void* param, calldata_t* data); + + static void OnMediaPlaying(void* param, calldata_t* data); + static void OnMediaPaused(void* param, calldata_t* data); + static void OnMediaRestarted(void* param, calldata_t* data); + static void OnMediaStopped(void* param, calldata_t* data); + static void OnMediaNext(void* param, calldata_t* data); + static void OnMediaPrevious(void* param, calldata_t* data); + static void OnMediaStarted(void* param, calldata_t* data); + static void OnMediaEnded(void* param, calldata_t* data); static void OnSceneReordered(void* param, calldata_t* data); static void OnSceneItemAdd(void* param, calldata_t* data); diff --git a/src/WSRequestHandler.cpp b/src/WSRequestHandler.cpp index 514cf455..95741acd 100644 --- a/src/WSRequestHandler.cpp +++ b/src/WSRequestHandler.cpp @@ -28,7 +28,7 @@ using namespace std::placeholders; -const QHash WSRequestHandler::messageMap { +const QHash WSRequestHandler::messageMap{ { "GetVersion", &WSRequestHandler::GetVersion }, { "GetAuthRequired", &WSRequestHandler::GetAuthRequired }, { "Authenticate", &WSRequestHandler::Authenticate }, @@ -43,11 +43,19 @@ const QHash WSRequestHandler::messageMap { { "BroadcastCustomMessage", &WSRequestHandler::BroadcastCustomMessage }, + { "TriggerHotkeyByName", &WSRequestHandler::TriggerHotkeyByName }, + { "TriggerHotkeyBySequence", &WSRequestHandler::TriggerHotkeyBySequence }, + { "SetCurrentScene", &WSRequestHandler::SetCurrentScene }, { "GetCurrentScene", &WSRequestHandler::GetCurrentScene }, { "GetSceneList", &WSRequestHandler::GetSceneList }, + { "CreateScene", &WSRequestHandler::CreateScene }, + { "SetSceneTransitionOverride", &WSRequestHandler::SetSceneTransitionOverride }, + { "RemoveSceneTransitionOverride", &WSRequestHandler::RemoveSceneTransitionOverride }, + { "GetSceneTransitionOverride", &WSRequestHandler::GetSceneTransitionOverride }, { "SetSourceRender", &WSRequestHandler::SetSceneItemRender }, // Retrocompat + { "GetSceneItemList", &WSRequestHandler::GetSceneItemList }, { "SetSceneItemRender", &WSRequestHandler::SetSceneItemRender }, { "SetSceneItemPosition", &WSRequestHandler::SetSceneItemPosition }, { "SetSceneItemTransform", &WSRequestHandler::SetSceneItemTransform }, @@ -56,6 +64,7 @@ const QHash WSRequestHandler::messageMap { { "SetSceneItemProperties", &WSRequestHandler::SetSceneItemProperties }, { "ResetSceneItem", &WSRequestHandler::ResetSceneItem }, { "DeleteSceneItem", &WSRequestHandler::DeleteSceneItem }, + { "AddSceneItem", &WSRequestHandler::AddSceneItem }, { "DuplicateSceneItem", &WSRequestHandler::DuplicateSceneItem }, { "ReorderSceneItems", &WSRequestHandler::ReorderSceneItems }, @@ -66,11 +75,13 @@ const QHash WSRequestHandler::messageMap { { "StartStreaming", &WSRequestHandler::StartStreaming }, { "StopStreaming", &WSRequestHandler::StopStreaming }, + { "GetRecordingStatus", &WSRequestHandler::GetRecordingStatus }, { "StartRecording", &WSRequestHandler::StartRecording }, { "StopRecording", &WSRequestHandler::StopRecording }, { "PauseRecording", &WSRequestHandler::PauseRecording }, { "ResumeRecording", &WSRequestHandler::ResumeRecording }, + { "GetReplayBufferStatus", &WSRequestHandler::GetReplayBufferStatus }, { "StartStopReplayBuffer", &WSRequestHandler::StartStopReplayBuffer }, { "StartReplayBuffer", &WSRequestHandler::StartReplayBuffer }, { "StopReplayBuffer", &WSRequestHandler::StopReplayBuffer }, @@ -84,6 +95,9 @@ const QHash WSRequestHandler::messageMap { { "SetCurrentTransition", &WSRequestHandler::SetCurrentTransition }, { "SetTransitionDuration", &WSRequestHandler::SetTransitionDuration }, { "GetTransitionDuration", &WSRequestHandler::GetTransitionDuration }, + { "GetTransitionPosition", &WSRequestHandler::GetTransitionPosition }, + { "GetTransitionSettings", &WSRequestHandler::GetTransitionSettings }, + { "SetTransitionSettings", &WSRequestHandler::SetTransitionSettings }, { "ReleaseTBar", &WSRequestHandler::ReleaseTBar }, { "SetTBarPosition", &WSRequestHandler::SetTBarPosition }, @@ -92,6 +106,8 @@ const QHash WSRequestHandler::messageMap { { "ToggleMute", &WSRequestHandler::ToggleMute }, { "SetMute", &WSRequestHandler::SetMute }, { "GetMute", &WSRequestHandler::GetMute }, + { "GetAudioActive", &WSRequestHandler::GetAudioActive }, + { "SetSourceName", &WSRequestHandler::SetSourceName }, { "SetSyncOffset", &WSRequestHandler::SetSyncOffset }, { "GetSyncOffset", &WSRequestHandler::GetSyncOffset }, { "GetSpecialSources", &WSRequestHandler::GetSpecialSources }, @@ -99,6 +115,8 @@ const QHash WSRequestHandler::messageMap { { "GetSourceTypesList", &WSRequestHandler::GetSourceTypesList }, { "GetSourceSettings", &WSRequestHandler::GetSourceSettings }, { "SetSourceSettings", &WSRequestHandler::SetSourceSettings }, + { "GetAudioMonitorType", &WSRequestHandler::GetAudioMonitorType }, + { "SetAudioMonitorType", &WSRequestHandler::SetAudioMonitorType }, { "TakeSourceScreenshot", &WSRequestHandler::TakeSourceScreenshot }, { "GetSourceFilters", &WSRequestHandler::GetSourceFilters }, @@ -145,7 +163,19 @@ const QHash WSRequestHandler::messageMap { { "ListOutputs", &WSRequestHandler::ListOutputs }, { "GetOutputInfo", &WSRequestHandler::GetOutputInfo }, { "StartOutput", &WSRequestHandler::StartOutput }, - { "StopOutput", &WSRequestHandler::StopOutput } + { "StopOutput", &WSRequestHandler::StopOutput }, + + { "PlayPauseMedia", &WSRequestHandler::PlayPauseMedia }, + { "RestartMedia", &WSRequestHandler::RestartMedia }, + { "StopMedia", &WSRequestHandler::StopMedia }, + { "NextMedia", &WSRequestHandler::NextMedia }, + { "PreviousMedia", &WSRequestHandler::PreviousMedia }, + { "GetMediaDuration", &WSRequestHandler::GetMediaDuration }, + { "GetMediaTime", &WSRequestHandler::GetMediaTime }, + { "SetMediaTime", &WSRequestHandler::SetMediaTime }, + { "ScrubMedia", &WSRequestHandler::ScrubMedia }, + { "GetMediaState", &WSRequestHandler::GetMediaState }, + { "GetMediaSourcesList", &WSRequestHandler::GetMediaSourcesList } }; const QSet WSRequestHandler::authNotRequired { diff --git a/src/WSRequestHandler.h b/src/WSRequestHandler.h index c01ed313..e9c5b9e1 100644 --- a/src/WSRequestHandler.h +++ b/src/WSRequestHandler.h @@ -61,10 +61,18 @@ class WSRequestHandler { RpcResponse BroadcastCustomMessage(const RpcRequest&); + RpcResponse TriggerHotkeyByName(const RpcRequest&); + RpcResponse TriggerHotkeyBySequence(const RpcRequest&); + RpcResponse SetCurrentScene(const RpcRequest&); RpcResponse GetCurrentScene(const RpcRequest&); RpcResponse GetSceneList(const RpcRequest&); + RpcResponse CreateScene(const RpcRequest&); + RpcResponse SetSceneTransitionOverride(const RpcRequest&); + RpcResponse RemoveSceneTransitionOverride(const RpcRequest&); + RpcResponse GetSceneTransitionOverride(const RpcRequest&); + RpcResponse GetSceneItemList(const RpcRequest&); RpcResponse SetSceneItemRender(const RpcRequest&); RpcResponse SetSceneItemPosition(const RpcRequest&); RpcResponse SetSceneItemTransform(const RpcRequest&); @@ -74,6 +82,7 @@ class WSRequestHandler { RpcResponse ResetSceneItem(const RpcRequest&); RpcResponse DuplicateSceneItem(const RpcRequest&); RpcResponse DeleteSceneItem(const RpcRequest&); + RpcResponse AddSceneItem(const RpcRequest&); RpcResponse ReorderSceneItems(const RpcRequest&); RpcResponse GetStreamingStatus(const RpcRequest&); @@ -83,11 +92,13 @@ class WSRequestHandler { RpcResponse StartStreaming(const RpcRequest&); RpcResponse StopStreaming(const RpcRequest&); + RpcResponse GetRecordingStatus(const RpcRequest&); RpcResponse StartRecording(const RpcRequest&); RpcResponse StopRecording(const RpcRequest&); RpcResponse PauseRecording(const RpcRequest&); RpcResponse ResumeRecording(const RpcRequest&); + RpcResponse GetReplayBufferStatus(const RpcRequest&); RpcResponse StartStopReplayBuffer(const RpcRequest&); RpcResponse StartReplayBuffer(const RpcRequest&); RpcResponse StopReplayBuffer(const RpcRequest&); @@ -101,6 +112,9 @@ class WSRequestHandler { RpcResponse SetCurrentTransition(const RpcRequest&); RpcResponse SetTransitionDuration(const RpcRequest&); RpcResponse GetTransitionDuration(const RpcRequest&); + RpcResponse GetTransitionPosition(const RpcRequest&); + RpcResponse GetTransitionSettings(const RpcRequest&); + RpcResponse SetTransitionSettings(const RpcRequest&); RpcResponse ReleaseTBar(const RpcRequest&); RpcResponse SetTBarPosition(const RpcRequest&); @@ -109,6 +123,8 @@ class WSRequestHandler { RpcResponse ToggleMute(const RpcRequest&); RpcResponse SetMute(const RpcRequest&); RpcResponse GetMute(const RpcRequest&); + RpcResponse GetAudioActive(const RpcRequest&); + RpcResponse SetSourceName(const RpcRequest&); RpcResponse SetSyncOffset(const RpcRequest&); RpcResponse GetSyncOffset(const RpcRequest&); RpcResponse GetSpecialSources(const RpcRequest&); @@ -116,6 +132,8 @@ class WSRequestHandler { RpcResponse GetSourceTypesList(const RpcRequest&); RpcResponse GetSourceSettings(const RpcRequest&); RpcResponse SetSourceSettings(const RpcRequest&); + RpcResponse GetAudioMonitorType(const RpcRequest&); + RpcResponse SetAudioMonitorType(const RpcRequest&); RpcResponse TakeSourceScreenshot(const RpcRequest&); RpcResponse GetSourceFilters(const RpcRequest&); @@ -163,4 +181,16 @@ class WSRequestHandler { RpcResponse GetOutputInfo(const RpcRequest&); RpcResponse StartOutput(const RpcRequest&); RpcResponse StopOutput(const RpcRequest&); + + RpcResponse PlayPauseMedia(const RpcRequest&); + RpcResponse RestartMedia(const RpcRequest&); + RpcResponse StopMedia(const RpcRequest&); + RpcResponse NextMedia(const RpcRequest&); + RpcResponse PreviousMedia(const RpcRequest&); + RpcResponse GetMediaDuration(const RpcRequest&); + RpcResponse GetMediaTime(const RpcRequest&); + RpcResponse SetMediaTime(const RpcRequest&); + RpcResponse ScrubMedia(const RpcRequest&); + RpcResponse GetMediaState(const RpcRequest&); + RpcResponse GetMediaSourcesList(const RpcRequest&); }; diff --git a/src/WSRequestHandler_General.cpp b/src/WSRequestHandler_General.cpp index 416ac013..d42513bc 100644 --- a/src/WSRequestHandler_General.cpp +++ b/src/WSRequestHandler_General.cpp @@ -171,6 +171,7 @@ RpcResponse WSRequestHandler::Authenticate(const RpcRequest& request) { * @name SetHeartbeat * @category general * @since 4.3.0 + * @deprecated Since 4.9.0. Please poll the appropriate data using requests. Will be removed in v5.0.0. */ RpcResponse WSRequestHandler::SetHeartbeat(const RpcRequest& request) { if (!request.hasField("enable")) { @@ -231,7 +232,7 @@ RpcResponse WSRequestHandler::GetFilenameFormatting(const RpcRequest& request) { /** * Get OBS stats (almost the same info as provided in OBS' stats window) * - * @return {OBSStats} `stats` OBS stats + * @return {OBSStats} `stats` [OBS stats](#obsstats) * * @api requests * @name GetStats @@ -319,12 +320,12 @@ RpcResponse WSRequestHandler::GetVideoInfo(const RpcRequest& request) { /** * Open a projector window or create a projector on a monitor. Requires OBS v24.0.4 or newer. - * - * @param {String (Optional)} `type` Type of projector: Preview (default), Source, Scene, StudioProgram, or Multiview (case insensitive). + * + * @param {String (Optional)} `type` Type of projector: `Preview` (default), `Source`, `Scene`, `StudioProgram`, or `Multiview` (case insensitive). * @param {int (Optional)} `monitor` Monitor to open the projector on. If -1 or omitted, opens a window. - * @param {String (Optional)} `geometry` Size and position of the projector window (only if monitor is -1). Encoded in Base64 using Qt's geometry encoding (https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors. + * @param {String (Optional)} `geometry` Size and position of the projector window (only if monitor is -1). Encoded in Base64 using [Qt's geometry encoding](https://doc.qt.io/qt-5/qwidget.html#saveGeometry). Corresponds to OBS's saved projectors. * @param {String (Optional)} `name` Name of the source or scene to be displayed (ignored for other projector types). - * + * * @api requests * @name OpenProjector * @category general @@ -344,3 +345,73 @@ RpcResponse WSRequestHandler::OpenProjector(const RpcRequest& request) { obs_frontend_open_projector(type, monitor, geometry, name); return request.success(); } + +/** +* Executes hotkey routine, identified by hotkey unique name +* +* @param {String} `hotkeyName` Unique name of the hotkey, as defined when registering the hotkey (e.g. "ReplayBuffer.Save") +* +* @api requests +* @name TriggerHotkeyByName +* @category general +* @since unreleased +*/ +RpcResponse WSRequestHandler::TriggerHotkeyByName(const RpcRequest& request) { + const char* name = obs_data_get_string(request.parameters(), "hotkeyName"); + + obs_hotkey_t* hk = Utils::FindHotkeyByName(name); + if (!hk) { + return request.failed("hotkey not found"); + } + obs_hotkey_trigger_routed_callback(obs_hotkey_get_id(hk), true); + return request.success(); +} + +/** +* Executes hotkey routine, identified by bound combination of keys. A single key combination might trigger multiple hotkey routines depending on user settings +* +* @param {String} `keyId` Main key identifier (e.g. `OBS_KEY_A` for key "A"). Available identifiers [here](https://github.com/obsproject/obs-studio/blob/master/libobs/obs-hotkeys.h) +* @param {Object (Optional)} `keyModifiers` Optional key modifiers object. False entries can be ommitted +* @param {boolean} `keyModifiers.shift` Trigger Shift Key +* @param {boolean} `keyModifiers.alt` Trigger Alt Key +* @param {boolean} `keyModifiers.control` Trigger Control (Ctrl) Key +* @param {boolean} `keyModifiers.command` Trigger Command Key (Mac) +* +* @api requests +* @name TriggerHotkeyBySequence +* @category general +* @since unreleased +*/ +RpcResponse WSRequestHandler::TriggerHotkeyBySequence(const RpcRequest& request) { + if (!request.hasField("keyId")) { + return request.failed("missing request keyId parameter"); + } + + OBSDataAutoRelease data = obs_data_get_obj(request.parameters(), "keyModifiers"); + + obs_key_combination_t combo = {0}; + uint32_t modifiers = 0; + if (obs_data_get_bool(data, "shift")) + modifiers |= INTERACT_SHIFT_KEY; + if (obs_data_get_bool(data, "control")) + modifiers |= INTERACT_CONTROL_KEY; + if (obs_data_get_bool(data, "alt")) + modifiers |= INTERACT_ALT_KEY; + if (obs_data_get_bool(data, "command")) + modifiers |= INTERACT_COMMAND_KEY; + + combo.modifiers = modifiers; + combo.key = obs_key_from_name(obs_data_get_string(request.parameters(), "keyId")); + + if (!modifiers + && (combo.key == OBS_KEY_NONE || combo.key >= OBS_KEY_LAST_VALUE)) { + return request.failed("invalid key-modifier combination"); + } + + // Inject hotkey press-release sequence + obs_hotkey_inject_event(combo, false); + obs_hotkey_inject_event(combo, true); + obs_hotkey_inject_event(combo, false); + + return request.success(); +} diff --git a/src/WSRequestHandler_MediaControl.cpp b/src/WSRequestHandler_MediaControl.cpp new file mode 100644 index 00000000..225c40c5 --- /dev/null +++ b/src/WSRequestHandler_MediaControl.cpp @@ -0,0 +1,396 @@ +#include "Utils.h" + +#include "WSRequestHandler.h" + +bool isMediaSource(const QString& sourceKind) +{ + return (sourceKind == "vlc_source" || sourceKind == "ffmpeg_source"); +} + +QString getSourceMediaState(obs_source_t *source) +{ + QString mediaState; + enum obs_media_state mstate = obs_source_media_get_state(source); + switch (mstate) { + case OBS_MEDIA_STATE_NONE: + mediaState = "none"; + break; + case OBS_MEDIA_STATE_PLAYING: + mediaState = "playing"; + break; + case OBS_MEDIA_STATE_OPENING: + mediaState = "opening"; + break; + case OBS_MEDIA_STATE_BUFFERING: + mediaState = "buffering"; + break; + case OBS_MEDIA_STATE_PAUSED: + mediaState = "paused"; + break; + case OBS_MEDIA_STATE_STOPPED: + mediaState = "stopped"; + break; + case OBS_MEDIA_STATE_ENDED: + mediaState = "ended"; + break; + case OBS_MEDIA_STATE_ERROR: + mediaState = "error"; + break; + default: + mediaState = "unknown"; + } + return mediaState; +} + +/** +* Pause or play a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* @param {boolean} `playPause` Whether to pause or play the source. `false` for play, `true` for pause. +* +* @api requests +* @name PlayPauseMedia +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::PlayPauseMedia(const RpcRequest& request) { + if ((!request.hasField("sourceName")) || (!request.hasField("playPause"))) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + bool playPause = obs_data_get_bool(request.parameters(), "playPause"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + obs_source_media_play_pause(source, playPause); + return request.success(); +} + +/** +* Restart a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* +* @api requests +* @name RestartMedia +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::RestartMedia(const RpcRequest& request) { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + obs_source_media_restart(source); + return request.success(); +} + +/** +* Stop a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* +* @api requests +* @name StopMedia +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::StopMedia(const RpcRequest& request) { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + obs_source_media_stop(source); + return request.success(); +} + +/** +* Skip to the next media item in the playlist. Supports only vlc media source (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* +* @api requests +* @name NextMedia +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::NextMedia(const RpcRequest& request) { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + obs_source_media_next(source); + return request.success(); +} + +/** +* Go to the previous media item in the playlist. Supports only vlc media source (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* +* @api requests +* @name PreviousMedia +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::PreviousMedia(const RpcRequest& request) { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + obs_source_media_previous(source); + return request.success(); +} + +/** +* Get the length of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* Note: For some reason, for the first 5 or so seconds that the media is playing, the total duration can be off by upwards of 50ms. +* +* @param {String} `sourceName` Source name. +* +* @return {int} `mediaDuration` The total length of media in milliseconds.. +* +* @api requests +* @name GetMediaDuration +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_int(response, "mediaDuration", obs_source_media_get_duration(source)); + return request.success(response); +} + +/** +* Get the current timestamp of media in milliseconds. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* +* @return {int} `timestamp` The time in milliseconds since the start of the media. +* +* @api requests +* @name GetMediaTime +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_int(response, "timestamp", obs_source_media_get_time(source)); + return request.success(response); +} + +/** +* Set the timestamp of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* @param {int} `timestamp` Milliseconds to set the timestamp to. +* +* @api requests +* @name SetMediaTime +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) { + if (!request.hasField("sourceName") || !request.hasField("timestamp")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + int64_t timestamp = (int64_t)obs_data_get_int(request.parameters(), "timestamp"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + obs_source_media_set_time(source, timestamp); + return request.success(); +} + +/** +* Scrub media using a supplied offset. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* Note: Due to processing/network delays, this request is not perfect. The processing rate of this request has also not been tested. +* +* @param {String} `sourceName` Source name. +* @param {int} `timeOffset` Millisecond offset (positive or negative) to offset the current media position. +* +* @api requests +* @name ScrubMedia +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::ScrubMedia(const RpcRequest& request) { + if (!request.hasField("sourceName") || !request.hasField("timeOffset")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + int64_t timeOffset = (int64_t)obs_data_get_int(request.parameters(), "timeOffset"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + int64_t newTime = obs_source_media_get_time(source) + timeOffset; + if (newTime < 0) { + newTime = 0; + } + + obs_source_media_set_time(source, newTime); + return request.success(); +} + +/** +* Get the current playing state of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8) +* +* @param {String} `sourceName` Source name. +* +* @return {String} `mediaState` The media state of the provided source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown` +* +* @api requests +* @name GetMediaState +* @category media control +* @since unreleased +*/ +RpcResponse WSRequestHandler::GetMediaState(const RpcRequest& request) { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_string(response, "mediaState", getSourceMediaState(source).toUtf8()); + + return request.success(response); +} + +/** +* List the media state of all media sources (vlc and media source) +* +* @return {Array} `mediaSources` Array of sources +* @return {String} `mediaSources.*.sourceName` Unique source name +* @return {String} `mediaSources.*.sourceKind` Unique source internal type (a.k.a `ffmpeg_source` or `vlc_source`) +* @return {String} `mediaSources.*.mediaState` The current state of media for that source. States: `none`, `playing`, `opening`, `buffering`, `paused`, `stopped`, `ended`, `error`, `unknown` +* +* @api requests +* @name GetMediaSourcesList +* @category sources +* @since unreleased +*/ +RpcResponse WSRequestHandler::GetMediaSourcesList(const RpcRequest& request) +{ + OBSDataArrayAutoRelease sourcesArray = obs_data_array_create(); + + auto sourceEnumProc = [](void* privateData, obs_source_t* source) -> bool { + obs_data_array_t* sourcesArray = (obs_data_array_t*)privateData; + + QString sourceKind = obs_source_get_id(source); + if (isMediaSource(sourceKind)) { + OBSDataAutoRelease sourceData = obs_data_create(); + obs_data_set_string(sourceData, "sourceName", obs_source_get_name(source)); + obs_data_set_string(sourceData, "sourceKind", sourceKind.toUtf8()); + + QString mediaState = getSourceMediaState(source); + obs_data_set_string(sourceData, "mediaState", mediaState.toUtf8()); + + obs_data_array_push_back(sourcesArray, sourceData); + } + return true; + }; + obs_enum_sources(sourceEnumProc, sourcesArray); + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_array(response, "mediaSources", sourcesArray); + return request.success(response); +} diff --git a/src/WSRequestHandler_Outputs.cpp b/src/WSRequestHandler_Outputs.cpp index dad0bf19..ab8b0cc1 100644 --- a/src/WSRequestHandler_Outputs.cpp +++ b/src/WSRequestHandler_Outputs.cpp @@ -71,7 +71,7 @@ RpcResponse findOutputOrFail(const RpcRequest& request, std::function(param)); + }, (void*)profileName, true); + return request.success(); } /** * Get the name of the current profile. - * + * * @return {String} `profile-name` Name of the currently active profile. * * @api requests @@ -49,6 +58,7 @@ RpcResponse WSRequestHandler::GetCurrentProfile(const RpcRequest& request) { * Get a list of available profiles. * * @return {Array} `profiles` List of available profiles. + * @return {String} `profiles.*.profile-name` Filter name * * @api requests * @name ListProfiles diff --git a/src/WSRequestHandler_Recording.cpp b/src/WSRequestHandler_Recording.cpp index df2ed4a0..24aba87a 100644 --- a/src/WSRequestHandler_Recording.cpp +++ b/src/WSRequestHandler_Recording.cpp @@ -1,8 +1,10 @@ +#include "obs-websocket.h" #include "WSRequestHandler.h" #include #include #include "Utils.h" +#include "WSEvents.h" RpcResponse ifCanPause(const RpcRequest& request, std::function callback) { @@ -13,8 +15,35 @@ RpcResponse ifCanPause(const RpcRequest& request, std::function c return callback(); } + /** + * Get current recording status. + * + * @return {boolean} `isRecording` Current recording status. + * @return {boolean} `isRecordingPaused` Whether the recording is paused or not. + * @return {String (optional)} `recordTimecode` Time elapsed since recording started (only present if currently recording). + * + * @api requests + * @name GetRecordingStatus + * @category recording + * @since unreleased + */ +RpcResponse WSRequestHandler::GetRecordingStatus(const RpcRequest& request) { + auto events = GetEventsSystem(); + + OBSDataAutoRelease data = obs_data_create(); + obs_data_set_bool(data, "isRecording", obs_frontend_recording_active()); + obs_data_set_bool(data, "isRecordingPaused", obs_frontend_recording_paused()); + + if (obs_frontend_recording_active()) { + QString recordingTimecode = events->getRecordingTimecode(); + obs_data_set_string(data, "recordTimecode", recordingTimecode.toUtf8().constData()); + } + + return request.success(data); +} + /** - * Toggle recording on or off. + * Toggle recording on or off (depending on the current recording state). * * @api requests * @name StartStopRecording diff --git a/src/WSRequestHandler_ReplayBuffer.cpp b/src/WSRequestHandler_ReplayBuffer.cpp index 510b8f05..d4c83a27 100644 --- a/src/WSRequestHandler_ReplayBuffer.cpp +++ b/src/WSRequestHandler_ReplayBuffer.cpp @@ -1,9 +1,29 @@ +#include "obs-websocket.h" +#include "WSEvents.h" #include "Utils.h" #include "WSRequestHandler.h" + + /** + * Get the status of the OBS replay buffer. + * + * @return {boolean} `isReplayBufferActive` Current recording status. + * + * @api requests + * @name GetReplayBufferStatus + * @category replay buffer + * @since unreleased + */ +RpcResponse WSRequestHandler::GetReplayBufferStatus(const RpcRequest& request) { + OBSDataAutoRelease data = obs_data_create(); + obs_data_set_bool(data, "isReplayBufferActive", obs_frontend_replay_buffer_active()); + + return request.success(data); +} + /** -* Toggle the Replay Buffer on/off. +* Toggle the Replay Buffer on/off (depending on the current state of the replay buffer). * * @api requests * @name StartStopReplayBuffer diff --git a/src/WSRequestHandler_SceneCollections.cpp b/src/WSRequestHandler_SceneCollections.cpp index 1f87996b..77ce5d0a 100644 --- a/src/WSRequestHandler_SceneCollections.cpp +++ b/src/WSRequestHandler_SceneCollections.cpp @@ -17,13 +17,22 @@ RpcResponse WSRequestHandler::SetCurrentSceneCollection(const RpcRequest& reques return request.failed("missing request parameters"); } - QString sceneCollection = obs_data_get_string(request.parameters(), "sc-name"); - if (sceneCollection.isEmpty()) { + const char* sceneCollection = obs_data_get_string(request.parameters(), "sc-name"); + if (!sceneCollection) { return request.failed("invalid request parameters"); } - // TODO : Check if specified profile exists and if changing is allowed - obs_frontend_set_current_scene_collection(sceneCollection.toUtf8()); + char** collections = obs_frontend_get_scene_collections(); + bool collectionExists = Utils::StringInStringList(collections, sceneCollection); + bfree(collections); + if (!collectionExists) { + return request.failed("scene collection does not exist"); + } + + obs_queue_task(OBS_TASK_UI, [](void* param) { + obs_frontend_set_current_scene_collection(reinterpret_cast(param)); + }, (void*)sceneCollection, true); + return request.success(); } @@ -51,6 +60,7 @@ RpcResponse WSRequestHandler::GetCurrentSceneCollection(const RpcRequest& reques * List available scene collections * * @return {Array} `scene-collections` Scene collections list + * @return {String} `scene-collections.*.sc-name` Scene collection name * * @api requests * @name ListSceneCollections diff --git a/src/WSRequestHandler_SceneItems.cpp b/src/WSRequestHandler_SceneItems.cpp index c1fd8522..2d09780d 100644 --- a/src/WSRequestHandler_SceneItems.cpp +++ b/src/WSRequestHandler_SceneItems.cpp @@ -2,6 +2,90 @@ #include "WSRequestHandler.h" +struct AddSourceData { + obs_source_t *source; + obs_sceneitem_t *sceneItem; + bool setVisible; +}; + +void AddSourceHelper(void *_data, obs_scene_t *scene) { + auto *data = reinterpret_cast(_data); + data->sceneItem = obs_scene_add(scene, data->source); + obs_sceneitem_set_visible(data->sceneItem, data->setVisible); +} + +/** +* Get a list of all scene items in a scene. +* +* @param {String (optional)} `sceneName` Name of the scene to get the list of scene items from. Defaults to the current scene if not specified. +* +* @return {String} `sceneName` Name of the requested (or current) scene +* @return {Array} `sceneItems` Array of scene items +* @return {int} `sceneItems.*.itemId` Unique item id of the source item +* @return {String} `sceneItems.*.sourceKind` ID if the scene item's source. For example `vlc_source` or `image_source` +* @return {String} `sceneItems.*.sourceName` Name of the scene item's source +* @return {String} `sceneItems.*.sourceType` Type of the scene item's source. Either `input`, `group`, or `scene` +* +* @api requests +* @name GetSceneItemList +* @category scene items +* @since unreleased +*/ +RpcResponse WSRequestHandler::GetSceneItemList(const RpcRequest& request) { + const char* sceneName = obs_data_get_string(request.parameters(), "sceneName"); + + OBSSourceAutoRelease sceneSource; + if (sceneName && strcmp(sceneName, "") != 0) { + sceneSource = obs_get_source_by_name(sceneName); + } else { + sceneSource = obs_frontend_get_current_scene(); + } + + OBSScene scene = obs_scene_from_source(sceneSource); + if (!scene) { + return request.failed("requested scene is invalid or doesnt exist"); + } + + OBSDataArrayAutoRelease sceneItemArray = obs_data_array_create(); + + auto sceneItemEnumProc = [](obs_scene_t *, obs_sceneitem_t* item, void* privateData) -> bool { + obs_data_array_t* sceneItemArray = (obs_data_array_t*)privateData; + + OBSDataAutoRelease sceneItemData = obs_data_create(); + obs_data_set_int(sceneItemData, "itemId", obs_sceneitem_get_id(item)); + OBSSource source = obs_sceneitem_get_source(item); + obs_data_set_string(sceneItemData, "sourceKind", obs_source_get_id(source)); + obs_data_set_string(sceneItemData, "sourceName", obs_source_get_name(source)); + + QString typeString = ""; + enum obs_source_type sourceType = obs_source_get_type(source); + switch (sourceType) { + case OBS_SOURCE_TYPE_INPUT: + typeString = "input"; + break; + + case OBS_SOURCE_TYPE_SCENE: + typeString = "scene"; + break; + + default: + typeString = "unknown"; + break; + } + obs_data_set_string(sceneItemData, "sourceType", typeString.toUtf8()); + + obs_data_array_push_back(sceneItemArray, sceneItemData); + return true; + }; + obs_scene_enum_items(scene, sceneItemEnumProc, sceneItemArray); + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_string(response, "sceneName", obs_source_get_name(sceneSource)); + obs_data_set_array(response, "sceneItems", sceneItemArray); + + return request.success(response); +} + /** * Gets the scene specific properties of the specified source item. * Coordinates are relative to the item's parent (the scene or group it belongs to). @@ -13,8 +97,8 @@ * * @return {String} `name` Scene Item name. * @return {int} `itemId` Scene Item ID. -* @return {int} `position.x` The x position of the source from the left. -* @return {int} `position.y` The y position of the source from the top. +* @return {double} `position.x` The x position of the source from the left. +* @return {double} `position.y` The y position of the source from the top. * @return {int} `position.alignment` The point on the source that the item is manipulated from. * @return {double} `rotation` The clockwise rotation of the item in degrees around the point of alignment. * @return {double} `scale.x` The x-scale factor of the source. @@ -37,7 +121,7 @@ * @return {int} `alignment` The point on the source that the item is manipulated from. The sum of 1=Left or 2=Right, and 4=Top or 8=Bottom, or omit to center on that axis. * @return {String (optional)} `parentGroupName` Name of the item's parent (if this item belongs to a group) * @return {Array (optional)} `groupChildren` List of children (if this item is a group) -* +* * @api requests * @name GetSceneItemProperties * @category scene items @@ -79,8 +163,8 @@ RpcResponse WSRequestHandler::GetSceneItemProperties(const RpcRequest& request) * @param {String | Object} `item` Scene Item name (if this field is a string) or specification (if it is an object). * @param {String (optional)} `item.name` Scene Item name (if the `item` field is an object) * @param {int (optional)} `item.id` Scene Item ID (if the `item` field is an object) -* @param {int (optional)} `position.x` The new x position of the source. -* @param {int (optional)} `position.y` The new y position of the source. +* @param {double (optional)} `position.x` The new x position of the source. +* @param {double (optional)} `position.y` The new y position of the source. * @param {int (optional)} `position.alignment` The new alignment of the source. * @param {double (optional)} `rotation` The new clockwise rotation of the item in degrees. * @param {double (optional)} `scale.x` The new x scale of the item. @@ -134,10 +218,10 @@ RpcResponse WSRequestHandler::SetSceneItemProperties(const RpcRequest& request) vec2 newPosition = oldPosition; if (obs_data_has_user_value(reqPosition, "x")) { - newPosition.x = obs_data_get_int(reqPosition, "x"); + newPosition.x = obs_data_get_double(reqPosition, "x"); } if (obs_data_has_user_value(reqPosition, "y")) { - newPosition.y = obs_data_get_int(reqPosition, "y"); + newPosition.y = obs_data_get_double(reqPosition, "y"); } if (obs_data_has_user_value(reqPosition, "alignment")) { @@ -164,7 +248,7 @@ RpcResponse WSRequestHandler::SetSceneItemProperties(const RpcRequest& request) vec2 newScale = oldScale; OBSDataAutoRelease reqScale = obs_data_get_obj(params, "scale"); - + if (obs_data_has_user_value(reqScale, "x")) { newScale.x = obs_data_get_double(reqScale, "x"); } @@ -252,7 +336,7 @@ RpcResponse WSRequestHandler::SetSceneItemProperties(const RpcRequest& request) } obs_sceneitem_set_bounds(sceneItem, &newBounds); - + if (obs_data_has_user_value(reqBounds, "alignment")) { const uint32_t bounds_alignment = obs_data_get_int(reqBounds, "alignment"); if (Utils::IsValidAlignment(bounds_alignment)) { @@ -329,7 +413,6 @@ RpcResponse WSRequestHandler::ResetSceneItem(const RpcRequest& request) { * @name SetSceneItemRender * @category scene items * @since 0.3 -* @deprecated Since 4.3.0. Prefer the use of SetSceneItemProperties. */ RpcResponse WSRequestHandler::SetSceneItemRender(const RpcRequest& request) { if (!request.hasField("source") || @@ -455,7 +538,7 @@ RpcResponse WSRequestHandler::SetSceneItemTransform(const RpcRequest& request) { obs_sceneitem_set_scale(sceneItem, &scale); obs_sceneitem_set_rot(sceneItem, rotation); - + obs_sceneitem_defer_update_end(sceneItem); return request.success(); @@ -544,6 +627,59 @@ RpcResponse WSRequestHandler::DeleteSceneItem(const RpcRequest& request) { return request.success(); } +/** + * Creates a scene item in a scene. In other words, this is how you add a source into a scene. + * + * @param {String} `sceneName` Name of the scene to create the scene item in + * @param {String} `sourceName` Name of the source to be added + * @param {boolean} `setVisible` Whether to make the sceneitem visible on creation or not. Default `true` + * + * @return {int} `itemId` Numerical ID of the created scene item + * + * @api requests + * @name AddSceneItem + * @category scene items + * @since unreleased + */ +RpcResponse WSRequestHandler::AddSceneItem(const RpcRequest& request) { + if (!request.hasField("sceneName") || !request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + const char* sceneName = obs_data_get_string(request.parameters(), "sceneName"); + OBSSourceAutoRelease sceneSource = obs_get_source_by_name(sceneName); + OBSScene scene = obs_scene_from_source(sceneSource); + if (!scene) { + return request.failed("requested scene is invalid or doesnt exist"); + } + + const char* sourceName = obs_data_get_string(request.parameters(), "sourceName"); + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName); + if (!source) { + return request.failed("requested source does not exist"); + } + + if (source == sceneSource) { + return request.failed("you cannot add a scene as a sceneitem to itself"); + } + + AddSourceData data; + data.source = source; + data.setVisible = true; + if (request.hasField("setVisible")) { + data.setVisible = obs_data_get_bool(request.parameters(), "setVisible"); + } + + obs_enter_graphics(); + obs_scene_atomic_update(scene, AddSourceHelper, &data); + obs_leave_graphics(); + + OBSDataAutoRelease responseData = obs_data_create(); + obs_data_set_int(responseData, "itemId", obs_sceneitem_get_id(data.sceneItem)); + + return request.success(responseData); +} + /** * Duplicates a scene item. * diff --git a/src/WSRequestHandler_Scenes.cpp b/src/WSRequestHandler_Scenes.cpp index 40693a78..9c317cdf 100644 --- a/src/WSRequestHandler_Scenes.cpp +++ b/src/WSRequestHandler_Scenes.cpp @@ -36,7 +36,7 @@ RpcResponse WSRequestHandler::SetCurrentScene(const RpcRequest& request) { /** * Get the current scene's name and source items. - * + * * @return {String} `name` Name of the currently active scene. * @return {Array} `sources` Ordered list of the current scene's source items. * @@ -58,7 +58,7 @@ RpcResponse WSRequestHandler::GetCurrentScene(const RpcRequest& request) { /** * Get a list of scenes in the currently active profile. - * + * * @return {String} `current-scene` Name of the currently active scene. * @return {Array} `scenes` Ordered list of the current profile's scenes (See [GetCurrentScene](#getcurrentscene) for more information). * @@ -79,13 +79,38 @@ RpcResponse WSRequestHandler::GetSceneList(const RpcRequest& request) { return request.success(data); } +/** + * Create a new scene scene. + * + * @param {String} `sceneName` Name of the scene to create. + * + * @api requests + * @name CreateScene + * @category scenes + * @since 4.8.0 + */ +RpcResponse WSRequestHandler::CreateScene(const RpcRequest& request) { + if (!request.hasField("sceneName")) { + return request.failed("missing request parameters"); + } + + const char* sceneName = obs_data_get_string(request.parameters(), "sceneName"); + OBSSourceAutoRelease source = obs_get_source_by_name(sceneName); + + if (source) { + return request.failed("scene with this name already exists"); + } + obs_scene_create(sceneName); + return request.success(); +} + /** * Changes the order of scene items in the requested scene. * * @param {String (optional)} `scene` Name of the scene to reorder (defaults to current). * @param {Array} `items` Ordered list of objects with name and/or id specified. Id preferred due to uniqueness per scene -* @param {int (optional)} `items[].id` Id of a specific scene item. Unique on a scene by scene basis. -* @param {String (optional)} `items[].name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene. +* @param {int (optional)} `items.*.id` Id of a specific scene item. Unique on a scene by scene basis. +* @param {String (optional)} `items.*.name` Name of a scene item. Sufficiently unique if no scene items share sources within the scene. * * @api requests * @name ReorderSceneItems @@ -121,7 +146,7 @@ RpcResponse WSRequestHandler::ReorderSceneItems(const RpcRequest& request) { struct obs_sceneitem_order_info info; size_t itemCount = obs_data_array_count(ctx->items); - for (int i = 0; i < itemCount; i++) { + for (uint i = 0; i < itemCount; i++) { OBSDataAutoRelease item = obs_data_array_item(ctx->items, i); OBSSceneItemAutoRelease sceneItem = Utils::GetSceneItemFromItem(scene, item); @@ -148,3 +173,128 @@ RpcResponse WSRequestHandler::ReorderSceneItems(const RpcRequest& request) { return request.success(); } + +/** + * Set a scene to use a specific transition override. + * + * @param {String} `sceneName` Name of the scene to switch to. + * @param {String} `transitionName` Name of the transition to use. + * @param {int (Optional)} `transitionDuration` Duration in milliseconds of the transition if transition is not fixed. Defaults to the current duration specified in the UI if there is no current override and this value is not given. + * + * @api requests + * @name SetSceneTransitionOverride + * @category scenes + * @since 4.8.0 + */ +RpcResponse WSRequestHandler::SetSceneTransitionOverride(const RpcRequest& request) { + if (!request.hasField("sceneName") || !request.hasField("transitionName")) { + return request.failed("missing request parameters"); + } + + QString sceneName = obs_data_get_string(request.parameters(), "sceneName"); + OBSSourceAutoRelease source = obs_get_source_by_name(sceneName.toUtf8()); + if (!source) { + return request.failed("requested scene does not exist"); + } + + enum obs_source_type sourceType = obs_source_get_type(source); + if (sourceType != OBS_SOURCE_TYPE_SCENE) { + return request.failed("requested scene is invalid"); + } + + QString transitionName = obs_data_get_string(request.parameters(), "transitionName"); + if (!Utils::GetTransitionFromName(transitionName)) { + return request.failed("requested transition does not exist"); + } + + OBSDataAutoRelease sourceData = obs_source_get_private_settings(source); + obs_data_set_string(sourceData, "transition", transitionName.toUtf8().constData()); + + if (request.hasField("transitionDuration")) { + int transitionOverrideDuration = obs_data_get_int(request.parameters(), "transitionDuration"); + obs_data_set_int(sourceData, "transition_duration", transitionOverrideDuration); + } else if(!obs_data_has_user_value(sourceData, "transition_duration")) { + obs_data_set_int(sourceData, "transition_duration", + obs_frontend_get_transition_duration() + ); + } + + return request.success(); +} + +/** + * Remove any transition override on a scene. + * + * @param {String} `sceneName` Name of the scene to switch to. + * + * @api requests + * @name RemoveSceneTransitionOverride + * @category scenes + * @since 4.8.0 + */ +RpcResponse WSRequestHandler::RemoveSceneTransitionOverride(const RpcRequest& request) { + if (!request.hasField("sceneName")) { + return request.failed("missing request parameters"); + } + + QString sceneName = obs_data_get_string(request.parameters(), "sceneName"); + OBSSourceAutoRelease source = obs_get_source_by_name(sceneName.toUtf8()); + if (!source) { + return request.failed("requested scene does not exist"); + } + + enum obs_source_type sourceType = obs_source_get_type(source); + if (sourceType != OBS_SOURCE_TYPE_SCENE) { + return request.failed("requested scene is invalid"); + } + + OBSDataAutoRelease sourceData = obs_source_get_private_settings(source); + obs_data_erase(sourceData, "transition"); + obs_data_erase(sourceData, "transition_duration"); + + return request.success(); +} + +/** + * Get the current scene transition override. + * + * @param {String} `sceneName` Name of the scene to switch to. + * + * @return {String} `transitionName` Name of the current overriding transition. Empty string if no override is set. + * @return {int} `transitionDuration` Transition duration. `-1` if no override is set. + * + * @api requests + * @name GetSceneTransitionOverride + * @category scenes + * @since 4.8.0 + */ +RpcResponse WSRequestHandler::GetSceneTransitionOverride(const RpcRequest& request) { + if (!request.hasField("sceneName")) { + return request.failed("missing request parameters"); + } + + QString sceneName = obs_data_get_string(request.parameters(), "sceneName"); + OBSSourceAutoRelease source = obs_get_source_by_name(sceneName.toUtf8()); + if (!source) { + return request.failed("requested scene does not exist"); + } + + enum obs_source_type sourceType = obs_source_get_type(source); + if (sourceType != OBS_SOURCE_TYPE_SCENE) { + return request.failed("requested scene is invalid"); + } + + OBSDataAutoRelease sourceData = obs_source_get_private_settings(source); + const char* transitionOverrideName = obs_data_get_string(sourceData, "transition"); + + bool hasDurationOverride = obs_data_has_user_value(sourceData, "transition_duration"); + int transitionOverrideDuration = obs_data_get_int(sourceData, "transition_duration"); + + OBSDataAutoRelease fields = obs_data_create(); + obs_data_set_string(fields, "transitionName", transitionOverrideName); + obs_data_set_int(fields, "transitionDuration", + (hasDurationOverride ? transitionOverrideDuration : -1) + ); + + return request.success(fields); +} diff --git a/src/WSRequestHandler_Sources.cpp b/src/WSRequestHandler_Sources.cpp index 03a01de1..ba98ecdb 100644 --- a/src/WSRequestHandler_Sources.cpp +++ b/src/WSRequestHandler_Sources.cpp @@ -23,7 +23,7 @@ bool isTextFreeType2Source(const QString& sourceKind) * * @return {Array} `sources` Array of sources * @return {String} `sources.*.name` Unique source name -* @return {String} `sources.*.typeId` Non-unique source internal type (a.k.a type id) +* @return {String} `sources.*.typeId` Non-unique source internal type (a.k.a kind) * @return {String} `sources.*.type` Source type. Value is one of the following: "input", "filter", "transition", "scene" or "unknown" * * @api requests @@ -156,12 +156,13 @@ RpcResponse WSRequestHandler::GetSourceTypesList(const RpcRequest& request) } /** -* Get the volume of the specified source. +* Get the volume of the specified source. Default response uses mul format, NOT SLIDER PERCENTAGE. * * @param {String} `source` Source name. +* @param {boolean (optional)} `useDecibel` Output volume in decibels of attenuation instead of amplitude/mul. * * @return {String} `name` Source name. -* @return {double} `volume` Volume of the source. Between `0.0` and `1.0`. +* @return {double} `volume` Volume of the source. Between `0.0` and `1.0` if using mul, under `0.0` if using dB (since it is attenuating). * @return {boolean} `muted` Indicates whether the source is muted. * * @api requests @@ -185,35 +186,50 @@ RpcResponse WSRequestHandler::GetVolume(const RpcRequest& request) return request.failed("specified source doesn't exist"); } + float volume = obs_source_get_volume(source); + + bool useDecibel = obs_data_get_bool(request.parameters(), "useDecibel"); + if (useDecibel) { + volume = obs_mul_to_db(volume); + } + + if (volume == -INFINITY) { + volume = -100.0; + } + OBSDataAutoRelease response = obs_data_create(); obs_data_set_string(response, "name", obs_source_get_name(source)); - obs_data_set_double(response, "volume", obs_source_get_volume(source)); + obs_data_set_double(response, "volume", volume); obs_data_set_bool(response, "muted", obs_source_muted(source)); - return request.success(response); } /** - * Set the volume of the specified source. - * - * @param {String} `source` Source name. - * @param {double} `volume` Desired volume. Must be between `0.0` and `1.0`. - * - * @api requests - * @name SetVolume - * @category sources - * @since 4.0.0 - */ +* Set the volume of the specified source. Default request format uses mul, NOT SLIDER PERCENTAGE. +* +* @param {String} `source` Source name. +* @param {double} `volume` Desired volume. Must be between `0.0` and `1.0` for mul, and under 0.0 for dB. Note: OBS will interpret dB values under -100.0 as Inf. +* @param {boolean (optional)} `useDecibel` Interperet `volume` data as decibels instead of amplitude/mul. +* +* @api requests +* @name SetVolume +* @category sources +* @since 4.0.0 +*/ RpcResponse WSRequestHandler::SetVolume(const RpcRequest& request) { if (!request.hasField("source") || !request.hasField("volume")) { return request.failed("missing request parameters"); } + bool useDecibel = obs_data_get_bool(request.parameters(), "useDecibel"); + QString sourceName = obs_data_get_string(request.parameters(), "source"); float sourceVolume = obs_data_get_double(request.parameters(), "volume"); - if (sourceName.isEmpty() || sourceVolume < 0.0 || sourceVolume > 1.0) { + bool isNotValidDecibel = (useDecibel && sourceVolume > 0.0); + bool isNotValidMul = (!useDecibel && (sourceVolume < 0.0 || sourceVolume > 1.0)); + if (sourceName.isEmpty() || isNotValidDecibel || isNotValidMul) { return request.failed("invalid request parameters"); } @@ -222,7 +238,11 @@ RpcResponse WSRequestHandler::SetVolume(const RpcRequest& request) return request.failed("specified source doesn't exist"); } + if (useDecibel) { + sourceVolume = obs_db_to_mul(sourceVolume); + } obs_source_set_volume(source, sourceVolume); + return request.success(); } @@ -325,6 +345,80 @@ RpcResponse WSRequestHandler::ToggleMute(const RpcRequest& request) return request.success(); } +/** +* Get the audio's active status of a specified source. +* +* @param {String} `sourceName` Source name. +* +* @return {boolean} `audioActive` Audio active status of the source. +* +* @api requests +* @name GetAudioActive +* @category sources +* @since unreleased +*/ +RpcResponse WSRequestHandler::GetAudioActive(const RpcRequest& request) +{ + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_bool(response, "audioActive", obs_source_audio_active(source)); + + return request.success(response); +} + +/** +* Sets (aka rename) the name of a source. Also works with scenes since scenes are technically sources in OBS. +* +* Note: If the new name already exists as a source, obs-websocket will return an error. +* +* @param {String} `sourceName` Source name. +* @param {String} `newName` New source name. +* +* @api requests +* @name SetSourceName +* @category sources +* @since 4.8.0 +*/ +RpcResponse WSRequestHandler::SetSourceName(const RpcRequest& request) +{ + if (!request.hasField("sourceName") || !request.hasField("newName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + QString newName = obs_data_get_string(request.parameters(), "newName"); + if (sourceName.isEmpty() || newName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + OBSSourceAutoRelease existingSource = obs_get_source_by_name(newName.toUtf8()); + if (!existingSource) { // OBS is supposed to automatically rename colliding source names, but it doesn't. So this gets to be the solution for now. + obs_source_set_name(source, newName.toUtf8()); + + return request.success(); + } else { + return request.failed("a source with that name already exists"); + } +} + /** * Set the audio sync offset of a specified source. * @@ -417,6 +511,7 @@ RpcResponse WSRequestHandler::GetSourceSettings(const RpcRequest& request) const char* sourceName = obs_data_get_string(request.parameters(), "sourceName"); OBSSourceAutoRelease source = obs_get_source_by_name(sourceName); + if (!source) { return request.failed("specified source doesn't exist"); } @@ -477,21 +572,17 @@ RpcResponse WSRequestHandler::SetSourceSettings(const RpcRequest& request) } } - OBSDataAutoRelease currentSettings = obs_source_get_settings(source); OBSDataAutoRelease newSettings = obs_data_get_obj(request.parameters(), "sourceSettings"); - OBSDataAutoRelease sourceSettings = obs_data_create(); - obs_data_apply(sourceSettings, currentSettings); - obs_data_apply(sourceSettings, newSettings); - - obs_source_update(source, sourceSettings); + obs_source_update(source, newSettings); obs_source_update_properties(source); + OBSDataAutoRelease updatedSettings = obs_source_get_settings(source); + OBSDataAutoRelease response = obs_data_create(); obs_data_set_string(response, "sourceName", obs_source_get_name(source)); obs_data_set_string(response, "sourceType", obs_source_get_id(source)); - obs_data_set_obj(response, "sourceSettings", sourceSettings); - + obs_data_set_obj(response, "sourceSettings", updatedSettings); return request.success(response); } @@ -502,8 +593,8 @@ RpcResponse WSRequestHandler::SetSourceSettings(const RpcRequest& request) * * @return {String} `source` Source name. * @return {String} `align` Text Alignment ("left", "center", "right"). - * @return {int} `bk-color` Background color. - * @return {int} `bk-opacity` Background opacity (0-100). + * @return {int} `bk_color` Background color. + * @return {int} `bk_opacity` Background opacity (0-100). * @return {boolean} `chatlog` Chat log. * @return {int} `chatlog_lines` Chat log lines. * @return {int} `color` Text color. @@ -562,8 +653,8 @@ RpcResponse WSRequestHandler::GetTextGDIPlusProperties(const RpcRequest& request * * @param {String} `source` Name of the source. * @param {String (optional)} `align` Text Alignment ("left", "center", "right"). - * @param {int (optional)} `bk-color` Background color. - * @param {int (optional)} `bk-opacity` Background opacity (0-100). + * @param {int (optional)} `bk_color` Background color. + * @param {int (optional)} `bk_opacity` Background opacity (0-100). * @param {boolean (optional)} `chatlog` Chat log. * @param {int (optional)} `chatlog_lines` Chat log lines. * @param {int (optional)} `color` Text color. @@ -919,7 +1010,7 @@ RpcResponse WSRequestHandler::SetTextFreetype2Properties(const RpcRequest& reque * @name GetBrowserSourceProperties * @category sources * @since 4.1.0 - * @deprecated Since 4.8.0. Prefer the use of GetSourceSettings. + * @deprecated Since 4.8.0. Prefer the use of GetSourceSettings. Will be removed in v5.0.0 */ RpcResponse WSRequestHandler::GetBrowserSourceProperties(const RpcRequest& request) { @@ -961,7 +1052,7 @@ RpcResponse WSRequestHandler::GetBrowserSourceProperties(const RpcRequest& reque * @api requests * @name SetBrowserSourceProperties * @category sources - * @deprecated Since 4.8.0. Prefer the use of SetSourceSettings. + * @deprecated Since 4.8.0. Prefer the use of SetSourceSettings. Will be removed in v5.0.0 * @since 4.1.0 */ RpcResponse WSRequestHandler::SetBrowserSourceProperties(const RpcRequest& request) @@ -1426,6 +1517,99 @@ RpcResponse WSRequestHandler::SetSourceFilterVisibility(const RpcRequest& reques return request.success(); } +/** +* Get the audio monitoring type of the specified source. +* +* @param {String} `sourceName` Source name. +* +* @return {String} `monitorType` The monitor type in use. Options: `none`, `monitorOnly`, `monitorAndOutput`. +* +* @api requests +* @name GetAudioMonitorType +* @category sources +* @since 4.8.0 +*/ +RpcResponse WSRequestHandler::GetAudioMonitorType(const RpcRequest& request) + { + if (!request.hasField("sourceName")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + + if (sourceName.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + OBSDataAutoRelease response = obs_data_create(); + + QString monitorType; + enum obs_monitoring_type mtype = obs_source_get_monitoring_type(source); + switch (mtype) { + case OBS_MONITORING_TYPE_NONE: + monitorType = "none"; + break; + case OBS_MONITORING_TYPE_MONITOR_ONLY: + monitorType = "monitorOnly"; + break; + case OBS_MONITORING_TYPE_MONITOR_AND_OUTPUT: + monitorType = "monitorAndOutput"; + break; + default: + monitorType = "unknown"; + break; + } + obs_data_set_string(response, "monitorType", monitorType.toUtf8()); + + return request.success(response); +} + +/** +* Set the audio monitoring type of the specified source. +* +* @param {String} `sourceName` Source name. +* @param {String} `monitorType` The monitor type to use. Options: `none`, `monitorOnly`, `monitorAndOutput`. +* +* @api requests +* @name SetAudioMonitorType +* @category sources +* @since 4.8.0 +*/ +RpcResponse WSRequestHandler::SetAudioMonitorType(const RpcRequest& request) + { + if (!request.hasField("sourceName") || !request.hasField("monitorType")) { + return request.failed("missing request parameters"); + } + + QString sourceName = obs_data_get_string(request.parameters(), "sourceName"); + QString monitorType = obs_data_get_string(request.parameters(), "monitorType"); + + if (sourceName.isEmpty() || monitorType.isEmpty()) { + return request.failed("invalid request parameters"); + } + + OBSSourceAutoRelease source = obs_get_source_by_name(sourceName.toUtf8()); + if (!source) { + return request.failed("specified source doesn't exist"); + } + + if (monitorType == "none") { + obs_source_set_monitoring_type(source, OBS_MONITORING_TYPE_NONE); + } else if (monitorType == "monitorOnly") { + obs_source_set_monitoring_type(source, OBS_MONITORING_TYPE_MONITOR_ONLY); + } else if (monitorType == "monitorAndOutput") { + obs_source_set_monitoring_type(source, OBS_MONITORING_TYPE_MONITOR_AND_OUTPUT); + } else { + return request.failed("invalid monitorType"); + } + return request.success(); +} + /** * Takes a picture snapshot of a source and then can either or both: * - Send it over as a Data URI (base64-encoded data) in the response (by specifying `embedPictureFormat` in the request) @@ -1436,9 +1620,11 @@ RpcResponse WSRequestHandler::SetSourceFilterVisibility(const RpcRequest& reques * Clients can specify `width` and `height` parameters to receive scaled pictures. Aspect ratio is * preserved if only one of these two parameters is specified. * -* @param {String} `sourceName` Source name. Note that, since scenes are also sources, you can also provide a scene name. +* @param {String (optional)} `sourceName` Source name. Note that, since scenes are also sources, you can also provide a scene name. If not provided, the currently active scene is used. * @param {String (optional)} `embedPictureFormat` Format of the Data URI encoded picture. Can be "png", "jpg", "jpeg" or "bmp" (or any other value supported by Qt's Image module) * @param {String (optional)} `saveToFilePath` Full file path (file extension included) where the captured image is to be saved. Can be in a format different from `pictureFormat`. Can be a relative path. +* @param {String (optional)} `fileFormat` Format to save the image file as (one of the values provided in the `supported-image-export-formats` response field of `GetVersion`). If not specified, tries to guess based on file extension. +* @param {int (optional)} `compressionQuality` Compression ratio between -1 and 100 to write the image with. -1 is automatic, 1 is smallest file/most compression, 100 is largest file/least compression. Varies with image type. * @param {int (optional)} `width` Screenshot width. Defaults to the source's base width. * @param {int (optional)} `height` Screenshot height. Defaults to the source's base height. * @@ -1452,18 +1638,19 @@ RpcResponse WSRequestHandler::SetSourceFilterVisibility(const RpcRequest& reques * @since 4.6.0 */ RpcResponse WSRequestHandler::TakeSourceScreenshot(const RpcRequest& request) { - if (!request.hasField("sourceName")) { - return request.failed("missing request parameters"); - } - if (!request.hasField("embedPictureFormat") && !request.hasField("saveToFilePath")) { return request.failed("At least 'embedPictureFormat' or 'saveToFilePath' must be specified"); } - const char* sourceName = obs_data_get_string(request.parameters(), "sourceName"); - OBSSourceAutoRelease source = obs_get_source_by_name(sourceName); - if (!source) { - return request.failed("specified source doesn't exist");; + OBSSourceAutoRelease source; + if (!request.hasField("sourceName")) { + source = obs_frontend_get_current_scene(); + } else { + const char* sourceName = obs_data_get_string(request.parameters(), "sourceName"); + source = obs_get_source_by_name(sourceName); + if (!source) { + return request.failed("specified source doesn't exist");; + } } const uint32_t sourceWidth = obs_source_get_base_width(source); @@ -1522,7 +1709,7 @@ RpcResponse WSRequestHandler::TakeSourceScreenshot(const RpcRequest& request) { gs_stage_texture(stagesurface, gs_texrender_get_texture(texrender)); if (gs_stagesurface_map(stagesurface, &videoData, &videoLinesize)) { int linesize = sourceImage.bytesPerLine(); - for (int y = 0; y < imgHeight; y++) { + for (uint y = 0; y < imgHeight; y++) { memcpy(sourceImage.scanLine(y), videoData + (y * videoLinesize), linesize); } gs_stagesurface_unmap(stagesurface); @@ -1541,20 +1728,30 @@ RpcResponse WSRequestHandler::TakeSourceScreenshot(const RpcRequest& request) { OBSDataAutoRelease response = obs_data_create(); + int compressionQuality {-1}; + if (request.hasField("compressionQuality")) { + compressionQuality = obs_data_get_int(request.parameters(), "compressionQuality"); + + if (compressionQuality < -1 || compressionQuality > 100) { + QString errorMessage = QString("compression quality out of range: %1").arg(compressionQuality); + return request.failed(errorMessage.toUtf8()); + } + } + if (request.hasField("embedPictureFormat")) { const char* pictureFormat = obs_data_get_string(request.parameters(), "embedPictureFormat"); QByteArrayList supportedFormats = QImageWriter::supportedImageFormats(); if (!supportedFormats.contains(pictureFormat)) { - QString errorMessage = QString("Unsupported picture format: %1").arg(pictureFormat); + QString errorMessage = QString("unsupported picture format: %1").arg(pictureFormat); return request.failed(errorMessage.toUtf8()); } QByteArray encodedImgBytes; QBuffer buffer(&encodedImgBytes); buffer.open(QBuffer::WriteOnly); - if (!sourceImage.save(&buffer, pictureFormat)) { - return request.failed("Embed image encoding failed"); + if (!sourceImage.save(&buffer, pictureFormat, compressionQuality)) { + return request.failed("embed image encoding failed"); } buffer.close(); @@ -1571,7 +1768,18 @@ RpcResponse WSRequestHandler::TakeSourceScreenshot(const RpcRequest& request) { QFileInfo filePathInfo(filePathStr); QString absoluteFilePath = filePathInfo.absoluteFilePath(); - if (!sourceImage.save(absoluteFilePath)) { + const char* fileFormat = nullptr; + if (request.hasField("fileFormat")) { + fileFormat = obs_data_get_string(request.parameters(), "fileFormat"); + QByteArrayList supportedFormats = QImageWriter::supportedImageFormats(); + + if (!supportedFormats.contains(fileFormat)) { + QString errorMessage = QString("unsupported file format: %1").arg(fileFormat); + return request.failed(errorMessage.toUtf8()); + } + } + + if (!sourceImage.save(absoluteFilePath, fileFormat, compressionQuality)) { return request.failed("Image save failed"); } obs_data_set_string(response, "imageFile", absoluteFilePath.toUtf8()); diff --git a/src/WSRequestHandler_Streaming.cpp b/src/WSRequestHandler_Streaming.cpp index 744a691f..aa0782c9 100644 --- a/src/WSRequestHandler_Streaming.cpp +++ b/src/WSRequestHandler_Streaming.cpp @@ -43,7 +43,7 @@ RpcResponse WSRequestHandler::GetStreamingStatus(const RpcRequest& request) { } /** - * Toggle streaming on or off. + * Toggle streaming on or off (depending on the current stream state). * * @api requests * @name StartStopStreaming @@ -103,10 +103,10 @@ RpcResponse WSRequestHandler::StartStreaming(const RpcRequest& request) { && obs_data_has_user_value(newSettings, "key")) { const char* key = obs_data_get_string(newSettings, "key"); - int keylen = strlen(key); + size_t keylen = strlen(key); bool hasQuestionMark = false; - for (int i = 0; i < keylen; i++) { + for (size_t i = 0; i < keylen; i++) { if (key[i] == '?') { hasQuestionMark = true; break; @@ -292,7 +292,6 @@ RpcResponse WSRequestHandler::SaveStreamSettings(const RpcRequest& request) { /** * Send the provided text as embedded CEA-608 caption data. - * As of OBS Studio 23.1, captions are not yet available on Linux. * * @param {String} `text` Captions text * diff --git a/src/WSRequestHandler_StudioMode.cpp b/src/WSRequestHandler_StudioMode.cpp index 042db61b..c5e33a70 100644 --- a/src/WSRequestHandler_StudioMode.cpp +++ b/src/WSRequestHandler_StudioMode.cpp @@ -133,6 +133,9 @@ RpcResponse WSRequestHandler::TransitionToProgram(const RpcRequest& request) { * @since 4.1.0 */ RpcResponse WSRequestHandler::EnableStudioMode(const RpcRequest& request) { + if (obs_frontend_preview_program_mode_active()) { + return request.failed("studio mode already active"); + } obs_queue_task(OBS_TASK_UI, [](void* param) { obs_frontend_set_preview_program_mode(true); @@ -150,6 +153,9 @@ RpcResponse WSRequestHandler::EnableStudioMode(const RpcRequest& request) { * @since 4.1.0 */ RpcResponse WSRequestHandler::DisableStudioMode(const RpcRequest& request) { + if (!obs_frontend_preview_program_mode_active()) { + return request.failed("studio mode not active"); + } obs_queue_task(OBS_TASK_UI, [](void* param) { obs_frontend_set_preview_program_mode(false); @@ -160,7 +166,7 @@ RpcResponse WSRequestHandler::DisableStudioMode(const RpcRequest& request) { } /** - * Toggles Studio Mode. + * Toggles Studio Mode (depending on the current state of studio mode). * * @api requests * @name ToggleStudioMode diff --git a/src/WSRequestHandler_Transitions.cpp b/src/WSRequestHandler_Transitions.cpp index 56505738..78d7ee30 100644 --- a/src/WSRequestHandler_Transitions.cpp +++ b/src/WSRequestHandler_Transitions.cpp @@ -121,6 +121,90 @@ RpcResponse WSRequestHandler::GetTransitionDuration(const RpcRequest& request) { return request.success(response); } +/** + * Get the position of the current transition. + * + * @return {double} `position` current transition position. This value will be between 0.0 and 1.0. Note: Transition returns 1.0 when not active. + * + * @api requests + * @name GetTransitionPosition + * @category transitions + * @since 4.8.0 + */ +RpcResponse WSRequestHandler::GetTransitionPosition(const RpcRequest& request) { + OBSSourceAutoRelease currentTransition = obs_frontend_get_current_transition(); + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_double(response, "position", obs_transition_get_time(currentTransition)); + + return request.success(response); +} + +/** + * Get the current settings of a transition + * + * @param {String} `transitionName` Transition name + * + * @return {Object} `transitionSettings` Current transition settings + * + * @api requests + * @name GetTransitionSettings + * @category transitions + * @since unreleased + */ +RpcResponse WSRequestHandler::GetTransitionSettings(const RpcRequest& request) { + if (!request.hasField("transitionName")) { + return request.failed("missing request parameters"); + } + + const char* transitionName = obs_data_get_string(request.parameters(), "transitionName"); + OBSSourceAutoRelease transition = Utils::GetTransitionFromName(transitionName); + if (!transition) { + return request.failed("specified transition doesn't exist"); + } + + OBSDataAutoRelease transitionSettings = obs_source_get_settings(transition); + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_obj(response, "transitionSettings", transitionSettings); + return request.success(response); +} + +/** + * Change the current settings of a transition + * + * @param {String} `transitionName` Transition name + * @param {Object} `transitionSettings` Transition settings (they can be partial) + * + * @return {Object} `transitionSettings` Updated transition settings + * + * @api requests + * @name SetTransitionSettings + * @category transitions + * @since unreleased + */ +RpcResponse WSRequestHandler::SetTransitionSettings(const RpcRequest& request) { + if (!request.hasField("transitionName") || !request.hasField("transitionSettings")) { + return request.failed("missing request parameters"); + } + + const char* transitionName = obs_data_get_string(request.parameters(), "transitionName"); + OBSSourceAutoRelease transition = Utils::GetTransitionFromName(transitionName); + if (!transition) { + return request.failed("specified transition doesn't exist"); + } + + OBSDataAutoRelease newSettings = obs_data_get_obj(request.parameters(), "transitionSettings"); + obs_source_update(transition, newSettings); + obs_source_update_properties(transition); + + OBSDataAutoRelease updatedSettings = obs_source_get_settings(transition); + + OBSDataAutoRelease response = obs_data_create(); + obs_data_set_obj(response, "transitionSettings", updatedSettings); + return request.success(response); +} + /** * Release the T-Bar. YOU MUST CALL THIS IF YOU SPECIFY `release = false` IN `SetTBarPosition`. * diff --git a/src/WSServer.cpp b/src/WSServer.cpp index 33f1bcbb..add0e1e1 100644 --- a/src/WSServer.cpp +++ b/src/WSServer.cpp @@ -60,10 +60,10 @@ WSServer::~WSServer() stop(); } -void WSServer::start(quint16 port) +void WSServer::start(quint16 port, bool lockToIPv4) { - if (_server.is_listening() && port == _serverPort) { - blog(LOG_INFO, "WSServer::start: server already on this port. no restart needed"); + if (_server.is_listening() && (port == _serverPort && _lockToIPv4 == lockToIPv4)) { + blog(LOG_INFO, "WSServer::start: server already on this port and protocol mode. no restart needed"); return; } @@ -74,9 +74,16 @@ void WSServer::start(quint16 port) _server.reset(); _serverPort = port; + _lockToIPv4 = lockToIPv4; websocketpp::lib::error_code errorCode; - _server.listen(_serverPort, errorCode); + if (lockToIPv4) { + blog(LOG_INFO, "WSServer::start: Locked to IPv4 bindings"); + _server.listen(websocketpp::lib::asio::ip::tcp::v4(), _serverPort, errorCode); + } else { + blog(LOG_INFO, "WSServer::start: Not locked to IPv4 bindings"); + _server.listen(_serverPort, errorCode); + } if (errorCode) { std::string errorCodeMessage = errorCode.message(); diff --git a/src/WSServer.h b/src/WSServer.h index 723f51af..1ca0734b 100644 --- a/src/WSServer.h +++ b/src/WSServer.h @@ -44,7 +44,7 @@ Q_OBJECT public: explicit WSServer(); virtual ~WSServer(); - void start(quint16 port); + void start(quint16 port, bool lockToIPv4); void stop(); void broadcast(const RpcEvent& event); QThreadPool* threadPool() { @@ -62,6 +62,7 @@ private: server _server; quint16 _serverPort; + bool _lockToIPv4; std::set> _connections; std::map> _connectionProperties; QMutex _clMutex; diff --git a/src/forms/settings-dialog.cpp b/src/forms/settings-dialog.cpp index 6aa2d4f1..ca686dfe 100644 --- a/src/forms/settings-dialog.cpp +++ b/src/forms/settings-dialog.cpp @@ -45,6 +45,7 @@ void SettingsDialog::showEvent(QShowEvent* event) { ui->serverEnabled->setChecked(conf->ServerEnabled); ui->serverPort->setValue(conf->ServerPort); + ui->lockToIPv4->setChecked(conf->LockToIPv4); ui->debugEnabled->setChecked(conf->DebugEnabled); ui->alertsEnabled->setChecked(conf->AlertsEnabled); @@ -72,6 +73,7 @@ void SettingsDialog::FormAccepted() { conf->ServerEnabled = ui->serverEnabled->isChecked(); conf->ServerPort = ui->serverPort->value(); + conf->LockToIPv4 = ui->lockToIPv4->isChecked(); conf->DebugEnabled = ui->debugEnabled->isChecked(); conf->AlertsEnabled = ui->alertsEnabled->isChecked(); @@ -95,7 +97,7 @@ void SettingsDialog::FormAccepted() { auto server = GetServer(); if (conf->ServerEnabled) { - server->start(conf->ServerPort); + server->start(conf->ServerPort, conf->LockToIPv4); } else { server->stop(); } diff --git a/src/forms/settings-dialog.ui b/src/forms/settings-dialog.ui index 6964a153..237fb932 100644 --- a/src/forms/settings-dialog.ui +++ b/src/forms/settings-dialog.ui @@ -2,150 +2,157 @@ SettingsDialog - - - 0 - 0 - 407 - 195 - - - - - 0 - 0 - - - - OBSWebsocket.Settings.DialogTitle - - - false - - - - QLayout::SetDefaultConstraint - - - - - - - OBSWebsocket.Settings.AuthRequired - - - - - - - OBSWebsocket.Settings.Password - - - - - - - QLineEdit::Password - - - - - - - OBSWebsocket.Settings.ServerEnable - - - true - - - - - - - OBSWebsocket.Settings.ServerPort - - - - - - - 1024 - - - 65535 - - - 4444 - - - - - - - OBSWebsocket.Settings.AlertsEnable - - - true - - - - - - - OBSWebsocket.Settings.DebugEnable - - - false - - - - - - - - - Qt::Horizontal - - - QDialogButtonBox::Cancel|QDialogButtonBox::Ok - - - - + + + 0 + 0 + 407 + 216 + + + + + 0 + 0 + + + + OBSWebsocket.Settings.DialogTitle + + + false + + + + QLayout::SetDefaultConstraint + + + + + + + OBSWebsocket.Settings.AuthRequired + + + + + + + OBSWebsocket.Settings.Password + + + + + + + QLineEdit::Password + + + + + + + OBSWebsocket.Settings.ServerEnable + + + true + + + + + + + OBSWebsocket.Settings.ServerPort + + + + + + + 1024 + + + 65535 + + + 4444 + + + + + + + OBSWebsocket.Settings.AlertsEnable + + + true + + + + + + + OBSWebsocket.Settings.DebugEnable + + + false + + + + + + + OBSWebsocket.Settings.LockToIPv4 + + + + + + + + + Qt::Horizontal + + + QDialogButtonBox::Cancel|QDialogButtonBox::Ok + + + + - - buttonBox - accepted() - SettingsDialog - accept() - - - 248 - 294 - - - 157 - 314 - - - - - buttonBox - rejected() - SettingsDialog - reject() - - - 316 - 300 - - - 286 - 314 - - - + + buttonBox + accepted() + SettingsDialog + accept() + + + 248 + 294 + + + 157 + 314 + + + + + buttonBox + rejected() + SettingsDialog + reject() + + + 316 + 300 + + + 286 + 314 + + + diff --git a/src/obs-websocket.cpp b/src/obs-websocket.cpp index 9f19ab9e..b198ebb7 100644 --- a/src/obs-websocket.cpp +++ b/src/obs-websocket.cpp @@ -81,7 +81,7 @@ bool obs_module_load(void) { auto eventCallback = [](enum obs_frontend_event event, void *param) { if (event == OBS_FRONTEND_EVENT_FINISHED_LOADING) { if (_config->ServerEnabled) { - _server->start(_config->ServerPort); + _server->start(_config->ServerPort, _config->LockToIPv4); } obs_frontend_remove_event_callback((obs_frontend_event_cb)param, nullptr); }