Develop
Bevara provides an SDK that can be used for both open-source development and proprietary-Accessor development.
Architecture
The Bevara series of IDEs use a proprietary algorithm to analyze an input data file to determine an optimal Accessor for the file, if available. An Accessor is a pipeline composed of one or more code elements (filters), that handle operations such as reading, decoding or interpreting, displaying or playing back, and controlling the playback of the file.
Although the Bevara Access analyzer recommends a series of a filters for a supported format, each IDE provides the capability of user-selection of filters from the associated open-source and/or proprietary libraries. Warning: when selecting or changing any filters to build the Required libraries, you should always confirm by using the Preview pane that your file is being played back/displayed correctly.
Once determined, the selected set of filters is packaged into a set of required libraries with associated Javascript control code, and a framework for code integration into websites or applications is produced.
Sample HTML Integration code for an image shows the single filter required for this format, ffmpeg-mpeg1, with filter version specified by “_1”.
The “canvas” tag specifes that the video will be drawn on an HTML canvas. The associated “universal-canvas” and “solver” JavaScript attributes are used to read the data file and build the pipeline using the specified filter(s).
For all types of data, the Bevara Access engine relies on the GPAC pipeline builder to link the filters and exeute the Accessor process. For an overview of GPAC pipeline builder see the Wiki. The key is that each filter has a carefully specified set of inputs and outputs so that a set of filters can be chained together to reliably produce the desired output for a given input.
Pipeline Construction
The Accessor pipeline is composed of one or more WebAssembly filter components with one or more associated Javascript (or other language) wrappers for user-interface and pipeline control. Each filter component and control file is labelled with a version number, e.g., solver_1.0.2.
Each filter has a strict number of inputs and outputs, with specified capabilites on each, to enable successful filter chaining to form the complete Accessor. This also enables straightforward filter substitution via one of the Filter Selection methods. However, the Accessor pipeline must be verified after filter changes to ensure it continues to operate as expected.
The Bevara Access IDE enables selection from any of the filters available in the open-source library. Bevara Access Premium IDE subscribers have acces to a larger selection of filters and can also edit filters in the IDE library and create and add proprietary filters to the IDE library. Open-source Developers can create and add open-source filters to the general Bevara libaray.
Filter Selection
Filters can be manually added or removed from the Accessor pipeline for a selected file.
Each of the available filters is listed within the filters pane on the right . With the Bevara Access IDE you have the option of adding a filter or removing a filter from the set of Required libraries using the Add to library or Remove from library buttons. Note that every time you generate a new set of Required libraries, you must confirm that the set is performs the correct playback or display of the associated data file.
Once a new filter is added, the pipeline construction process is re-run. If Bevara Access detects that the filter cannot be used in the pipeline, it will appear under the Unused tab.
Pipeline Verification
After a pipeline is modified by deleting, adding, or exchanging filters, it is necessary to verify that the new Accessor pipeline correctly displays or plays back the associated data file. Verify the display/playback in the Preview pane, including the functionality of any controls.
The message tabs, one or more of Integration, Options, Media info, Graph, Stats, and Unused, at the bottom of the Preview pane are use for verification and debugging. These may display any error messages, text-based or graphical filter chains, and decoding/interpreting statistics. See Accessor Options.
Site or App Integration
To use an Accessor the Accessor pipeline code and instructions must be integrated into website or application that supports Wasm and JS (or alternate control language). The Bevara Access IDEs automatically generate an integration code framework for an HTML-based application, including the selected pipeline filters and supported optional controls.
See Integration Code for an overview of using the generated filter pipeline in a website.
Open-Source Development
Open-source developers are encouraged to contribute to the Bevara open-source Accessor library through the use of the Bevara Open-Source SDK. Before installing or using the Open-Source SDK, developers must read and agree to the Bevara Open-Source Developer IDE Terms of Service. This is important to read carefully, because, in part, any Accessor or constituent filters you develop using the Bevara Open-Source Developer tools will be linked to the Bevara Open-Source project and available for general use subject to the underlying open-source license(s). You must make your developed filters available through a broad license such as LGPL.
The default open-source development IDE is Visual Studio Code with an integrated GitHub fork of a Bevara framework. The default languages are C and C++; however, other languages, such as Rust, Go, C#, and Java, are also supported.
Steps in adding a new open-source filter to the library:
Install Visual Studio Code
Agree to the Bevara Open-Source Developer IDE Terms of Service and install the Bevara Access Extension
Create a public GitHub respository
Create a filter in one of the supported languages
Navigate to a folder containing media and click on a file. The selected file does not have to be in a format supported by open-source Bevara Access.
Create a Bevara Access account and login through VS Code Accounts and login through VS Code Accounts
Choose Add Accessor from the Library Pane on the right
Select Create a new Accessor from the pop-up dialog
Enter your public GitHub repository’s URI, e.g., https://github.com/Bevara/Demo/
Insert your filter in the generated framework and specify the input(s) and output(s) of the filter and GPAC flags and structures
Commit and compile the filter
Add to the open-source set of filters via the Add latest filter version to Bevara library
Verify filter operation
Filter Creation Example
This example illustrates how to incorporate a decoder for simple BMP 1BPP images into the Bevara framework. The code can be found in the public respository https://github.com/Bevara/Demo.
Step 1: Install Visual Studio Code
Follow the instructions to Download and Install Visual Studio Code. Additionally, install git on your machine.
Step 2: Agree to the Bevara Open-Source Developer IDE Terms of Service
Before installing the Bevara Access Extension for Open-Source Developers, you must read and agree to the Bevara Open-Source Developer IDE Terms of Service. This is important to read carefully, because, in part, any Accessor or constituent filters you develop using the Bevara Open-Source Developer tools will become a part of the Bevara Open-Source project and available for general use subject to the underlying open-source license(s).
Step 3: Install the Bevara Access Extension
Follow the instructions to Install the Bevara Access Extension to Visual Studio Code
Step 4: Create a filter in one of the supported languages.
For this example, a filter that takes as input an entire BMP image in 1BPP format and decodes it into an RGB (24BPP) stream has been extracted from a more general BMP decoder. This is a simplified example, so much of the error checking has been removed. The orginal error codes have been converted to GPAC codes, which are used by the Bevara framework. Key codes are GF_OK, GF_NOT_SUPPORTED, and GF_OUT_OF_MEM. The remainder of the error codes can be found in the GPAC documentation.
Step 5: Navigate to the Bevara Access Panel
The easiest way to reach the Bevara Access panel is to open a folder with media files and select one. In this case, we select a demo BMP 1BPP file, BMP_1bpp_Demo_Image.bmp. Because the image appears in the Preview pane, we see that VS Code natively handles this type of BMP image. However, there is not yet a filter in the Bevara library that supports the format. This is indicated both by the informative pop-up and the lack of selected filter in the generated HTML code, as well as the error messages below the Preview panel:
Step 6: Login to Bevara and GitHub
Dismiss the pop-up and use the Accounts access to create and login to your Bevara Account and also login to your public GitHub repository. For both you must agree to provide VS code access to your accounts.
Step 7: Add a Bevara Accessor framework to your public repository
TIP
Open-source developers can only create a new accessor once per account and repository.
Select the Add Accessor button. In the pop-up select the Create a New Accessor tab, enter the name of your filter, leave the default template choice Use an empty template, and hit the Create empty filter button. When prompted, choose where to placed the cloned framework locally, and select to open the cloned repository in VS Code. You can then verify that the template was added to your public repository, e.g., https://github.com/BevaraDemo/BMP1BPP.
The template is cloned locally and access to the Bevara SDK features is provided:
Verify in GitHub that the new repository is created:
Step 8: Add filter code to the framework and specify the filter flags and input(s)/output(s)
The main functions and structures are found in the file base_filter.c. The files CMakeLists.txt and filter.json will be used to build the filter and link it into the Bevara Open-Source project. In this example we will insert our filter code into base_filter.c, specify all flags and each input and output required for the filter, and then customize the filter.
Step 8a: The entry point and filter register structure are dynCall_filter_register() and FilterRegister in file base_filter.c:
We will customize the GF_FilterRegister registration structure name, by changing it to BMP1BPPRegister and modify the name, description, and help fields. Input arguments are needed for control, e.g., selecting an in-filter scaling value, captions track, or sub-image. For this simple example we do not need any external control, and so set the args field value to NULL and leave the associated ExampleFilterArgs structure untouched. Similarly, the initialize and finalize functions can be used for purposes such as memory de/allocation, and initialization; for this example we will not use them, so we will leave them in place. We will customize the capabilities structure, the main function, process, and the configuration function, configure_pid. Finally, we will add an extra function, probe_data; this function will ensure that our passed-in data can be recognized by the Bevara Acccess processor:
Step 8b: The default filter capabilities:
We modify the default filter capabilities name to match what was set in the GF_FilterRegister structure and then specify input and output formats through the GF_FilterCapability structure. We will indicate that we only expect to handle an input file with a “bmp” extension and a mime-type “image/bmp” in the file extension and mime capabilities setting functions. Further, since this is an image, we expect only an ouput VISUAL stream type, so we can remove the AUDIO capabilities line. Finally, we can specify the CODEC_ID to be RAW, indicting the output property we expected to be connected to this filter. More information about capabilites and filter input specification can be found at GPAC CodecID and Filtering Input Streams
Step 8c: Rename the configuration process to match the name specified in the GF_FilterRegister structure. We will add in some basic sanity-checking to ensure that we exit early if the filter cannot be handled. Since we do not need custom filter checking, we can comment out the format checking:
We assign the input source, pid, to our src_pid, and immediately specify that the framing mode is GF_TRUE; this indicates that we expect that the data will be passed to the filter in a single chunk. Finally, we specify that the output will be a RAW, VISUAL stream in RGB format, and set the filter name:
Step 8d: The sample base_filter_process() function is the framework in which to insert the new filter code:
Rename the function to match what was specified in the GF_FilterRegister structure. Insert your filter code into base_filter.c. Note that the filter input is specified as data_src and the output as data_dst, so ensure that the input and output of your code is linked to these pointers. We will also specify the output format, e.g., width, height, and size.
Step 8e: Add a probe_data function as specifed in the GF_FilterRegister. Although the filter handles sanity checking of the input data’s header, this sets the MIME type based on the magic number so that the Bevara Accessor pipeline process will recognize the input data as a BMP file. You can make this function as simple or as elaborate as desired to sort the input as needed for various filter handling:
Step 9: Customize your filter name and integrate into the build and Bevara files
Step 9a: For this example we will rename base_filter.c to BMP1BPP_filter.c and then change both the source file name and the filter name in CMakeLists.txt:
Step 9b: Change the name of filter.json to match your selected filter name, in this case BMP1BPP.json. We will edit it to add the filter name and description that will appear in Bevara Open-Source Library, specify our new filter name and source file, and list the one or more file extensions we would like to associate with this filter:
Step 10: Commit the changes
Step 10a: Click on the Source Control icon:
Or, alternately, click on the Bevara SDK icon and the Commit and Push Changes button:
Step 10b: Add a commit message and click the Commit button:
Step 10c: Click the Sync Changes button:
The filter build is automatically initiated:
The build is marked as complete with a check. The log for each compilation step can be reached by the globe icon to the right of the step in the Bevara SDK panel:
Step 10d: Add the most-recently-generated filter to the Bevara Open-Source library via the Add latest filter version to Bevara library button.
The filter build that is added to the Library is indicated by green check mark. A pin icon next to the build number allows uninstalling/reinstalling the build in the Library.
Step 11: Verify the filter
Verify that your filter operates as expected. In this example case the filter BMP1BPP has been added to the library, the test image is correctly displayed, and the Bevara Access platform has selected the filter “BMP1BPP_1” (version 1 of the BMP1BPP filter) as shown in the generated HTML code:
Debugging
The Bevara SDK and open-source repositories include several tools for debugging filters. Filter install switch and Chrome Developer Tools
Installed Filter Switch
The currently-installed filter can easily be switched between builds. Within the Bevara SDK panel each successful build is indicated by a check mark, and the currently-installed build is indicated by a green check mark. To switch the installed filter use the pin to the right of the build number and re-open your test file:
Chrome Developer Tools
To step though filter execution, you can use Chrome DevTools with your compiled filter; see Debugging WebAssembly with Modern Tools. You will need to build the Bevara Open-Source Player, compile your filter locally with debug options, and integrate the filter into the player before launching DevTools.
TIP
We suggest using macOS or Linux for debugging.
Step 1: Clone the Bevara open-source player
Clone the player from https://github.com/Bevara/player.git
Step 2: Install and activate the correct version of emsdk
Install emsdk for your platform via instructions at https://emscripten.org/docs/getting_started/downloads.html. However, rather than installing and activating the latest version, you must make sure that the activated version matches EMSDK_VERS as found in player/filters/third_parties/emsdk_vers.txt
cd player/filters/third_parties/emsdk
source ./emsdk_env.sh
Step 3: Install cmake
Step 4: Configure and Build the Bevara Player
cd to the player directory
mkdir build
cd build/
../configure –enable-debug
Step 5: Build your filter with debug information
cd to your filter directory
mkdir build
cd build/
emcmake cmake -DCMAKE_BUILD_TYPE=DEBUG ../
This will yeild a .wasm file, e.g., BPP1BPP.wasm
TIP
The resulting .wasm file includes a pointer to the local source, and thus is not portable. You will have to perform debugging only or your local machine or re-build for each new debugging machine.
Step 6: Set the player data source and filter source
Copy the filter Wasm file to player/build/. Alternatively, make a link in player/build/ to your Wasm filter.
Copy your test data file to player/build/.
Modify the player/templates/index.html file to point to the test file and the filter. The index.html file contains several templates for different data formats. For the open-source example, BPP1BPP, we will use the img tag with universal-img (version 1) to display the data. Change the “src” attribute to the name of your local test data file. Change the “with” attribute to the name of your filter.
Step 7: Build the player and start the server
cd player/build
make
make serve
Step 8: Debug!
Open Chrome and go to localhost:8081/ to access your file
Use the Developer tools to debug. Make sure you have the C/C++ DevTools Support (DWARF) Chrome extension or equivalent installed to view your files.
Bevara Premium Development
Bevara Access Premium subscribers can use their Premium account which includes the following advantages:
– developers can produce proprietary filters that are not required to be added to the Bevara Open-Source Library
– developers can access an internal compiler rather than relying on the GitHub compiler for fast, dynamic compilation
– one-click debugger setup
– unlimited access to platform tempates
– JS and ArtPlayer integration for more complex user interaction
To upgrade to Bevara Premium contact our Sales Team.
Filter Creation
Premium Developers should begin by following the Open-Source Developer instructions, but login to the Bevara Authentication system using their Premium subscription account and login to their private GitHub repository.
To compile a filter using dynamic compilation go to the BEVARA SETTINGS subpanel and set the Use dynamic compilation flag to True:
Compilation is triggered using the Start Compilation button:
Compilation success is indicated by a check mark:
Add the filter to the filter library with the Add latest filter version to Bevara library button:
The version added is indicated by a green check mark next to the compilation number:
Verify the new filter’s operation in the preview panel and the HTML code:
Finally, commit your changes. Use the Source Control icon to bring up the commit and sync interface:
Set a message and then trigger the git commit with the Commit button:
Sync your changes with the Sync button:
Debugging
Debugging tools for the Premium Developer are the same as described under Open-Source Develoepr Debugging; however, a Premium subscription includes automated debugging tools and do not have to download and build the Player to debug their code.
TIP
We suggest using macOS or Linux for debugging.
To enable compilation with debug information, go to the BEVARA SETTINGS subpanel and set the Use dynamic compilation flag to True and then set the Compile with debug information flag to True:
Compilation is triggered using the Start Compilation button as described in the Filter Creation section:
Once compilation is successful, load a data file, e.g., a BMP 1BPP file, and use the Export as HTML Template to download the files needed to implement the filter:
