Skip to content

Latest commit

 

History

History
178 lines (132 loc) · 9.94 KB

README.md

File metadata and controls

178 lines (132 loc) · 9.94 KB
Raw

URL/API Source - Connect Anything to OBS

GitHub GitHub Workflow Status Total downloads GitHub release (latest by date) Discord

Download

Introduction

The URL/API Source is a plugin for OBS Studio that allows fetcing data from a URL, API endpoint or file and displays it as text, image or even audio. OBS Forums page | Blog post

If this free plugin has been valuable to you consider adding a ⭐ to this GH repo, rating it on OBS, subscribing to my YouTube channel where I post updates, and supporting my work on GitHub, Patreon or OpenCollective

Usage Tutorials

Watch quick tutorials on how to use and setup the URL/API source on your OBS scene.

Additional things to do with URL/API source to upgrade your content:

Inspiration

Out of ideas on what to do with URL/API Source? Here's a repo with 1,000s of public APIs https://github.com/public-apis/public-apis

Dynamic Templating

The URL source supports both input and output templating using the Inja engine.

Output templates include {{output}} in case of a singular extraction from the response or {{output1}},{{output2}},... in case of multiple extracted value. In addition the {{body}} variable contains the entire body of the response in case of JSON. Advanced output templating functions can be achieved through Inja like looping over arrays, etc.

The input template works for the URL (querystring or REST path) or the POST body

Use the {{input}} variable to insert the output from a Text source. Inja advanced templates are available too. A special function strftime is available for formatting the current time using conventions from C++ STL (strftime), as well as urlencode which is useful for dynamic input in the querystring.

HTML Subset

The internal template renderer supports HTML4 and CSS with a reduced subset of feautures. It is quite powerful and can render tables and apply various styling to the text.

Image render is supported with the <img /> tag, and external URLs are supported as well. For example <img src="{{output}}" /> could be used to dynamically render an image URL coming from the response.

Code Walkthrough

Watch an explanation of the major parts of the code and how they work together.

Features:

  • HTTP request types: GET, POST
  • Request headers (for e.g. API Key or Auth token)
  • Request body for POST
  • Multiple dynamic inputs from several Text or Image sources (base64)
  • Output parsing: JSON (JSONPointer & JSONPath), XML/HTML (XPath & XQuery), Key-Value, Regex and CSS selectors
  • Update timer for live updating data
  • Test of the request to find the right parsing
  • Output styling (font, color, etc.) and formatting (via regex post processing)
  • Output Image (via image URL or image data on the response)
  • Output text to external Text Source and audio to external Media Source
  • Output to multiple sources with one request (Output Mapping)
  • Multi-value (array, union) parsed output capture, object unpacking (via Inja)
  • Dynamic input aggregations (time-based, "empty"-based)
  • Websocket support

Coming soon:

  • Authentication (Basic, Digest, OAuth)
  • More parsing options (CSV, etc.)
  • More request types (HTTP PUT / DELETE / PATCH, and GraphQL)
  • More output formats (Markdown, slim, reStructured, HAML, etc.)

Check out our other plugins:

  • Background Removal removes background from webcam without a green screen.
  • Detect will find and track >80 types of objects in any source that provides an image in real-time
  • LocalVocal speech AI assistant plugin for real-time, local transcription (captions), translation and more language functions
  • Polyglot translation AI plugin for real-time, local translation to hunderds of languages
  • 🚧 Experimental 🚧 CleanStream for real-time filler word (uh,um) and profanity removal from live audio stream

If you like this work, which is given to you completely free of charge, please consider supporting it on GitHub: https://github.com/sponsors/royshil

Download

Check out the latest releases for downloads and install instructions.

Building

The plugin was built and tested on Mac OSX (Intel & Apple silicon), Windows and Linux.

Start by cloning this repo to a directory of your choice.

Getting Submodules

Before compiling, you need to fetch all the submodules. After cloning the repository, run the following command in the root directory of the project:

git submodule update --init --recursive

This will initialize and fetch all the necessary submodules for the project.

Mac OSX

Using the CI pipeline scripts, locally you would just call the zsh script. By default this builds a universal binary for both Intel and Apple Silicon. To build for a specific architecture please see .github/scripts/.build.zsh for the -arch options.

$ ./.github/scripts/build-macos -c Release

Install

The above script should succeed and the plugin files (e.g. obs-urlsource.plugin) will reside in the ./release/Release folder off of the root. Copy the .plugin file to the OBS directory e.g. ~/Library/Application Support/obs-studio/plugins.

To get .pkg installer file, run for example

$ ./.github/scripts/package-macos -c Release

(Note that maybe the outputs will be in the Release folder and not the install folder like pakage-macos expects, so you will need to rename the folder from build_x86_64/Release to build_x86_64/install)

Linux (Ubuntu)

Use the CI scripts again

$ ./.github/scripts/build-linux.sh

Copy the results to the standard OBS folders on Ubuntu

$ sudo cp -R release/RelWithDebInfo/lib/* /usr/lib/x86_64-linux-gnu/
$ sudo cp -R release/RelWithDebInfo/share/* /usr/share/

Note: The official OBS plugins guide recommends adding plugins to the ~/.config/obs-studio/plugins folder.

Windows

Use the CI scripts again, for example:

> .github/scripts/Build-Windows.ps1 -Target x64 -CMakeGenerator "Visual Studio 17 2022"

The build should exist in the ./release folder off the root. You can manually install the files in the OBS directory.