Upload Annotations to Xeno-canto

This guide explains how to use the Xeno-canto annotation upload feature in Raven Annotate. This feature allows you to create annotations in Raven Annotate and upload them directly to Xeno-canto.

Prerequisites

Before you begin, ensure you have a Xeno-canto API Key.

Note: To get an API key, you will need to create an account on the Xeno-canto website. Your API key will be listed on your account page.

Setting your Xeno-canto API Key

To allow Raven Annotate to communicate with Xeno-canto, you must first configure your API key in the application preferences:

1. Open Raven Annotate.
2. Navigate to Edit > Preferences.
3. Locate the General section.
4. Paste your API key into the Xeno-canto API key field.
5. Click Apply to save your changes.

Step-by-Step: Uploading Annotations

1. Loading a Xeno-canto File

Once your API key is configured, you can create annotations for a specific recording:

1. Go to the File menu and select Load from Xeno-canto…
2. A dialog box will appear, allowing you to specify a recording from the Xeno-canto database. The format can be just the record number (e.g., 18832), The number with ‘XC’ prefix (e.g., XC18832), or a URL for the recording (e.g., https://xeno-canto.org/18832).

The recording will be downloaded to your user ~/Downloads folder and opened in Raven Annotate. The Event Table columns will be automatically configured based on the metadata of the recording.

Now, you can create annotations.

2. Filling in the Upload Dialog

Once you are done annotating the file, it’s a good idea to save your event table in the .raventable format in case you need to open it again later.

To upload annotations, select File > Upload to Xeno-canto from the menu. Fill in the required fields, and any optional settings. More information on the Annota-JSON fields can be found in this Annota-JSON Article.

• Set Metadata: Fields that apply to all annotations in a given set.
• Optional Details: Fields that cover more detailed information about the data set.
• Column Mapping: This section maps the Event Table columns to the Xeno-canto annotation fields.

Note: You can save these settings as a Preset to easily reuse them later.

3. Verifying the Data

Before uploading the annotations, you can run basic verification of the JSON.

• Verify: Click the “Verify” button. This will check the JSON structure and format and provide feedback in the Results section.
• Errors and Warnings: Any errors will need to be corrected before uploading. Warnings are not critical but may indicate potential issues.

Exporting to JSON (Optional)

If you wish to inspect the raw data or use it in another application before importing:

1. Choose the Export to JSON option within the import dialog.
2. Save the file to your preferred location. This JSON file contains the structured data that will be sent to Xeno-canto.

4. Finalizing the Upload

Once you are satisfied with the data:

1. Click Upload to send the annotations to Xeno-canto.
2. Once the annotations are uploaded, they may be viewed on the Xeno-canto website at https://xeno-canto.org/account/annotations, and the import can be finalized there.