Audio files support annotation using audio region object labels and classifications. Audio regions can be applied to a range (duration in milliseconds) on the audio file. Classifications can only be applied to the entire audio file. Using the Encord SDK you can import audio region labels and classifications directly to audio files that already exist in an Annotate Project. You can also use the SDK to view labels and classifications that exist on an audio file.

​
Critical Information

Using classifications on an audio file is similar to using labels or classifications on a video file. There are some critical differences though:

  • 1 “frame” = 1 millisecond for audio files when importing classifications.

  • When creating a classification for an audio file, the classification_instance uses the range_only=True argument.

For example, Classification.create_instance(range_only=True) or classification_instance = ClassificationInstance(range_only=True)


ranges = []
for range in classification_instance.get_ranges():
   ranges.append([range.start, range.end])

​
Audio Regions on Audio Files

​
Export Audio Regions on Audio Files


# Import dependencies
from pathlib import Path
from encord import EncordUserClient, Project
import json

SSH_PATH = "<file-path-to-your-ssh-key>"
PROJECT_HASH = "<project-unique-id>"

# Create user client using ssh key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get project for which predictions are to be added
project: Project = user_client.get_project(PROJECT_HASH)

# Get label rows for your Project
label_rows = project.list_label_rows_v2()

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

# Output directory for JSON files
output_dir = Path("./label_exports")
output_dir.mkdir(exist_ok=True)

# Export each label row to a JSON file
for label_row in label_rows:
    # Convert label row to dictionary
    label_data = label_row.to_encord_dict()

    # Save the label data to a JSON file
    file_name = f"{label_row.data_title}.json"
    output_path = output_dir / file_name

    with open(output_path, "w", encoding="utf-8") as json_file:
        json.dump(label_data, json_file, indent=4)

    print(f"Exported {label_row.data_title} to {output_path}")

print("All labels have been exported!")

​
Import Audio Regions to Audio Files


# Import dependencies
from pathlib import Path

from encord import EncordUserClient, Project
from encord.objects import (
    Object,
    ObjectInstance,
)
from encord.objects.coordinates import AudioCoordinates
from encord.objects.frames import Range

SSH_PATH = "<fie-path-to-your-ssh-key>"
PROJECT_HASH = "<project-unique-id>"

# Create user client using SSH private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    Path(SSH_PATH).read_text()
)

# Get the project for which predictions are to be added
project: Project = user_client.get_project(PROJECT_HASH)

# Example mapping of data unit titles to start and end frame ranges

audio_ranges = {
    "<audio-file-01>": [(<start-range-value>, <end-range-value>), (<start-range-value>, <end-range-value>), (<start-range-value>, <end-range-value>)],
    "<audio-file-02>": [(<start-range-value>, <end-range-value>), (<start-range-value>, <end-range-value>)],
    "<audio-file-03>": [(<start-range-value>, <end-range-value>)],
}

# Find the ontology object for your Audio Region
audio_ontology_object: Object = project.ontology_structure.get_child_by_title(
    title="<audio-region-name>", type_=Object
)

if audio_ontology_object is None:
    raise ValueError("Audio Region ontology object not found.")

label_rows = project.list_label_rows_v2()

# Filter label rows not in range
def filter_label_rows(label_row) -> bool:
    is_valid = label_row.data_title in audio_ranges
    if not is_valid:
        print(f"Skipping label row: {label_row_title} (no predefined ranges)")
    return is_valid

label_rows = list(filter(filter_label_rows, label_rows))

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

# Loop through each label row and apply updates
for label_row in label_rows:
    label_row_title = label_row.data_title

    # Apply all ranges as separate objects
    for start, end in audio_ranges.get(label_row_title, []):

        # Instantiate an object instance from the ontology node
        audio_object_instance: ObjectInstance = audio_ontology_object.create_instance()

        # Set object instance with specific start and end frames
        audio_object_instance.set_for_frames(

            coordinates=AudioCoordinates(range=[Range(start=start, end=end)]),  # Adjust as needed
            frames=0,

            manual_annotation=True,
            confidence=1.0,
        )

        # Link the object instance to the label row
        label_row.add_object_instance(audio_object_instance)

        print(f"Added range ({start}, {end}) to label row: {label_row_title}")

    # Upload the label to the server after adding all instances
    label_row.save()
    print(f"Saved label row: {label_row_title}")

print("Updates applied with predefined frame ranges for each data unit!")

​
Classifications on Audio Files

​
View Classifications on Audio Files


# Import dependencies
from encord import EncordUserClient

# Instantiate client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify Project
project = user_client.get_project("<project_id>")

# Downloads a local copy of all the labels
label_rows = project.list_label_rows_v2(include_all_label_branches=True) 

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    print(f"Title: {label_row.data_title}, branch: {label_row.branch_name}")

    # Print all essential classification information
    for classification_instance in label_row.get_classification_instances():
        print(f"classificationHash: {classification_instance.classification_hash}")
        print(f"Classification name: {classification_instance.classification_name}")
        print(f"featureHash: {classification_instance.feature_hash}")
        print(f"Classification answer: {classification_instance.get_answer().value}")
        print(f"Classification answer hash: {classification_instance.get_answer().feature_node_hash}")

​
Export Classifications from Audio Files

Template

# Import dependencies
from encord import EncordUserClient
import json

SSH_PATH = "<path-to-your-ssh-private-key>"

PROJECT_ID = "<your-project-id>"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify Project
project = user_client.get_project(PROJECT_ID)

# Downloads a local copy of all the labels
label_rows = project.list_label_rows_v2(include_all_label_branches=True) 

# Initialize label rows using bundles
with project.create_bundle() as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

for label_row in label_rows:
    print(f"Title: {label_row.data_title}, branch: {label_row.branch_name}")

    # Export classifications
    classifications = []
    for classification_instance in label_row.get_classification_instances():
        classification_data = {
            "classificationHash": classification_instance.classification_hash,
            "name": classification_instance.classification_name,
            "featureHash": classification_instance.feature_hash,
            "answer": classification_instance.get_answer().value,
            "answerHash": classification_instance.get_answer().feature_node_hash,
        }
        classifications.append(classification_data)
    
    # Print or save the exported classifications
    print(json.dumps(classifications, indent=2))
    # Alternatively, you can save to a file:
    # with open(f"{label_row.data_title}_classifications.json", "w") as f:
    #     json.dump(classifications, f, indent=2)

​
Import Classifications to Audio Files


# Import dependencies
from pathlib import Path
from encord import EncordUserClient, Project
from encord.objects import Classification
from encord.objects.options import Option

SSH_PATH = "<file-path-to-your-ssh-key>"
PROJECT_ID = "<project-unique-id>"

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Specify the project
project = user_client.get_project(PROJECT_ID)

# Define a mapping where each file has a list of classifications and options
file_classification_mapping = {
    "<audio-file-01.file-extension>": [
        {"classification_name": "<classification-name-01>", "option_title": "<option-value>"},
        {"classification_name": "<classification-name-02>", "option_title": "<option-value>"},
    ],
    "<audio-file-02.file-extension>": [
        {"classification_name": "<classification-name-01>", "option_title": "<option-value>"},
    ],
    "<audio-file-03.file-extension>": [
        {"classification_name": "<classification-name-01>", "option_title": "<option-value>"},
    ],
    # Add more mappings as needed
}

# Loop through the mapping to apply classifications to each unique file
for file_name, classifications in file_classification_mapping.items():
    try:
        # Fetch the label row for the given file name
        label_row = project.list_label_rows_v2(data_title_eq=file_name)[0]

        print(label_row.data_hash)

        label_row.initialise_labels()

        for classification_data in classifications:
            # Fetch the classification from the ontology
            ontology_classification: Classification = project.ontology_structure.get_child_by_title(
                title=classification_data["classification_name"],
                type_=Classification,
            )

            # Fetch the classification option
            option = ontology_classification.get_child_by_title(
                title=classification_data["option_title"], type_=Option
            )

            # Create a classification instance
            # range_only=True must be used when creating the classification
            classification_instance = ontology_classification.create_instance(range_only=True)
            classification_instance.set_answer(answer=option)

            # Set classification to apply to frame 0
            classification_instance.set_for_frames(
                frames=0,
                manual_annotation=True,
                confidence=1.0,
            )

            # Add classification instance to the label row
            label_row.add_classification_instance(classification_instance)

        # Save the updated label row after all classifications are added
        label_row.save()

        print(f"Successfully updated classifications for {file_name}.")
    except Exception as e:
        print(f"Failed to update classifications for {file_name}: {e}")