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()

# 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:
    # Download label information
    label_row.initialise_labels()

    # 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.")

# Loop through each label row and apply updates
for label_row in project.list_label_rows_v2():
    label_row_title = label_row.data_title

    # Skip if the title is not in the audio ranges

    if label_row_title not in audio_ranges:
        print(f"Skipping label row: {label_row_title} (no predefined ranges)")
        continue

    # Initialize labels for the label row
    label_row.initialise_labels()

    # 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) 

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

    # Download the label content
    label_row.initialise_labels()

    # 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) 

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

    # Download the label content
    label_row.initialise_labels()

    # 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}")

Was this page helpful?

BitmasksHTML Files and Labels