Using CLAMS App
This document provides general instructions for installing and using CLAMS Apps. App developers may provide additional information specific to their app, hence it’s advised also to look up the app website (or code repository) to get the additional information.
Generally, a CLAMS App requires
- To run the app locally, Python3 with the
clams-pythonmodule installed. Python 3.8 or higher is required.
- To run the app in a container (as an HTTP server), container management software such as
- (the CLAMS team is using
dockerfor development and testing)
- (the CLAMS team is using
- To invoke and execute analysis, HTTP client utility (such as
For Python dependencies, usually CLAMS Apps come with
requirements.txt files that list up the Python library.
However, there could be other non-Python software/library that are required by the app.
CLAMS Apps available on the CLAMS App Directory. Currently all CLAMS Apps are open-source projects and are distributed as
- source code downloadable from code repository
- pre-built container image
Please visit the app-directory to see which apps are available and where you can download them.
In most cases, you can “install” a CLAMS App by either
- downloading source code from the app code repository and manually building a container image
- downloading pre-built container image directly
Build image from source code
To download the source code, you can either use
git clone command or download a zip file from the source code repository.
The source code repository address can be found on the App Directory entry of the app.
From the locally downloaded project directory, run the following in your terminal to build an image from the included container specification file.
(Assuming you are using
docker as your container manager)
docker build . -f Containerfile -t <image_name_you_pick>
Download prebuilt image
Alternatively, the app maybe already be available on a container registry.
docker pull <prebulit_image_name>
The image name can be found on the App Directory entry of the app.
Running CLAMS App
Running as a container
Once the image is built (by
build) or downloaded (by
pull), to create a container, run:
docker run -v /path/to/data/directory:/data -p <port>:5000 <image_name>
/path/to/data/directory is the local location of your media files or MMIF objects and
<port> is the host port number you want your container to be listening to.
The HTTP inside the container will be listening to 5000 by default. Usually any number above 1024 is fine for the host port number, and you can use the same 5000 number for the host port number.
Note If you are using a Mac, on recent versions of macOS, port 5000 is used by Airplay Receiver by default. So you may need to use a different port number, or turn off the Airplay Receiver in the System Preferences to release 5000. For more information on safe port numbers, see IANA Port Number Registry or Wikipedia.
Note Another note for users of recent Macs with Apple Silicon (M1, M2, etc) CPU: you might see the following error message when you run the container image.
The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
This is because the image you are trying to run is built for Intel/AMC CPUs. To force the container to run on an emulation layer, you can add
--platform linux/amd64option to the
Running as a local HTTP server
To run the app as a local HTTP server without containerization, you can run the following command from the source code directory.
- By default, a CLAMS App will be listening to port 5000, but you can change the port number by passing
- Be default, the app will be running in debugging mode, but you can change it to production mode by passing
--productionoption to support larger traffic volume.
Running as a CLI program
(Not all CLAMS Apps can be run as a CLI program)
Many CLAMS Apps are written to work as a CLI-based Python Program, although they are primarily designed to be run as an HTTP server. CLI-based execution is useful for testing and debugging purposes, and varies from app to app. To see the command line interface, please visit the app source code repository and look for additional instructions from the app developer.
Invoking the app server
Once the app is running as an HTTP server, visit the server address (localhost:5000)to get the app metadata. App metadata is also available at the App Directory entry of the app. App metadata contains important information about the app that we will use in the following sections.
Processing input media
To actually run the app and process input media through computational analysis, simply send a POST request to the app with a MMIF input as the request body.
MMIF input files can be obtained from outputs of other CLAMS apps, or you can create an empty MMIF only with source media locations using
clams source command. See the help message for a more detailed instructions.
(Make sure you have installed
clams-python package version from PyPI.)
pip install clams-python
clams source --help
For example; by running
clams source audio:/data/audio/some-audio-file.mp3
You will get
If an app requires just
Document inputs (see
input section of the app metadata), an empty MMIF with required media file locations will suffice. The location has to be a URL or an absolute path, and it is important to ensure that it exists.
However, some apps only works with input MMIF that already contains some annotations of specific types. To run such apps, you need to run different apps in a sequence.
(TODO: added CLAMS workflow documentation link here.)
When an input MMIF is ready, you can send it to the app server.
Here’s an example of how to use the
curl command, and store the response in a file
curl -H "Accept: application/json" -X POST -email@example.com -s http://localhost:5000 > output.mmif
# or using a bash pipeline
clams source audio:/data/audio/some-audio-file.mp3 | curl -X POST -d@- -s http://localhost:5000 > output.mmif
?pretty=True to the URL will result in a pretty printed output. Note that when you’re using
curl from a shell session, you need to escape the
& characters with
\ to prevent the shell from interpreting it as a special character.
Configuring the app
Running as an HTTP server, CLAMS Apps are stateless, but can be configured for each HTTP request by providing configuration parameters as query string.
For configuration parameters, please look for
parameter section of the app metadata.