Edit Speakers and Create Document (Current)

This API involves editing a speaker using the enhanced speakerObj structure.

✅ Current Implementation: This page contains the latest recommended approach for editing speakers using the enhanced speakerObj structure. For legacy documentation, see Edit Speakers (Legacy).

API v2 Endpoint

All examples in this documentation use the new API v2 endpoint:

 https://api-v2.speechmind.com/external/v2/graphql

Once the protocol data is retrieved, the speakerList field (a JSON-stringified object) contains detailed timing and text segments for each speaker.

Example structure:

"mX9z2K4pR7qL8nE1bF5j": { //speaker unique identifier (slug)
    "speaker_name": {
        "givenName": "Emma",
        "familyName": "Wilson",
        "gender": "f",
        "party": null,
        "preTitel": null,
        "postTitel": null,
        "specialCase": false,
        "posShort": "CEO",
        "posLong": "Chief Executive Officer"
    },
    "duration": 42.15,
    "textsegment": [
        {
            "id": 201,
            "time": {
                "start_time": 8.20,
                "end_time": 15.45
            },
            "text": "Welcome everyone to our quarterly planning meeting.",
            "textsegment_duration": 7.25
        },
        {
            "id": 203,
            "time": {
                "start_time": 18.30,
                "end_time": 28.90
            },
            "text": "I'd like to review our progress and discuss the upcoming initiatives for next quarter.",
            "textsegment_duration": 10.60
        },
        {
            "id": 205,
            "time": {
                "start_time": 32.10,
                "end_time": 42.15
            },
            "text": "Let's start with the financial overview from our CFO.",
            "textsegment_duration": 10.05
        }
    ]
}

textJson Explanation:

The textJson field is a JSON-stringified array of objects, each representing a sentence spoken by the speaker. It contains:

• text: The sentence spoken.
• startTime: When the sentence begins (in seconds).
• endTime: When the sentence ends (in seconds).

Current Speaker Editing Process:

• Run the renameSpeakerInTextsegment mutation.

Current Mutation Structure

export const RENAME_SPEAKER_IN_TEXTSEGMENT = `
    fragment textsegmentDetails on ApiTextsegmentTypeWithSpeaker {
        id
        speakerObj {
            slug
            gender
            givenName
            familyName
            preTitel
            postTitel
            posShort
            posLong
        }
        textJson {
            text
            startTime
            endTime
        }
        pos
    }

    mutation RenameSpeakerInTextsegment($protocolSlug:String!, $speakerJson:[SpeakerDataInput!]!){
        renameSpeakerInTextsegment(protocolSlug:$protocolSlug, speakerJson:$speakerJson){
            success
            textsegmentsForRename{
                ...textsegmentDetails
            }
        }
    }
`;

Parameters for renameSpeakerInTextsegment Mutation

1. protocolSlug

• A unique identifier (slug) for the protocol (meeting or document) where you want to rename the speakers.
• Example: protocolSlug: "abc123xyz789example"

2. speakerJson

To rename speakers, provide an array with SpeakerDataInput objects. Each object uses the speaker’s oldSlug to identify them and allows updating all speaker properties:

{
  "protocolSlug": "abc123xyz789example",
  "speakerJson": [
    {
        "oldSlug": "mX9z2K4pR7qL8nE1bF5j",
        "givenName": "Alice",
        "familyName": "Johnson",
        "preTitel": null,
        "postTitel": null,
        "gender": "f",
        "party": null,
        "posLong": "Project Manager",
        "posShort": "PM"
    },
    {
        "oldSlug": "pQ8v3N6wY9sH2kD4fG7x",
        "givenName": "Bob",
        "familyName": "Smith",
        "preTitel": "Dr.",
        "postTitel": null,
        "gender": "m",
        "party": null,
        "posLong": "Senior Developer",
        "posShort": "Dev"
    }
  ]
}

Current JavaScript Implementation

import axios from "axios";

async function renameSpeakerInTextsegment(protocolSlug, speakerJson) {
    const dataObj = {
        query: RENAME_SPEAKER_IN_TEXTSEGMENT,
        variables: {
            protocolSlug: protocolSlug,
            speakerJson: speakerJson, // No need to JSON.stringify anymore
        },
    };

    return await axios({
        method: "post",
        url: process.env.VUE_APP_GRAPHQL_API,
        data: JSON.stringify(dataObj),
        headers: {
            "Content-Type": "application/json",
            "x-api-key": process.env.VUE_APP_API_KEY,
        },
    })
    .then((response) => {
        const responseData = response.data.data.renameSpeakerInTextsegment;
        
        return responseData;
    })
    .catch((error) => {
        console.log(error);
    });
}

Example Response Structure

The mutation returns a response with the enhanced speakerObj structure:

{
    "data": {
        "renameSpeakerInTextsegment": {
            "success": true,
            "textsegmentsForRename": [
                {
                    "id": "101",
                    "speakerObj": {
                        "slug": "mX9z2K4pR7qL8nE1bF5j",
                        "gender": "f",
                        "givenName": "Alice",
                        "familyName": "Johnson",
                        "preTitel": null,
                        "postTitel": null,
                        "posShort": "PM",
                        "posLong": "Project Manager"
                    },
                    "textJson": [
                        {
                            "text": "Good morning everyone. Let's review our project progress.",
                            "startTime": 5.20,
                            "endTime": 12.80
                        },
                        {
                            "text": "We have made significant improvements in the last sprint.",
                            "startTime": 13.15,
                            "endTime": 18.50
                        }
                    ],
                    "pos": 1
                },
                {
                    "id": "102",
                    "speakerObj": {
                        "slug": "pQ8v3N6wY9sH2kD4fG7x",
                        "gender": "m",
                        "givenName": "Bob",
                        "familyName": "Smith",
                        "preTitel": "Dr.",
                        "postTitel": null,
                        "posShort": "Dev",
                        "posLong": "Senior Developer"
                    },
                    "textJson": [
                        {
                            "text": "Thank you Alice. The technical implementation is progressing well.",
                            "startTime": 19.40,
                            "endTime": 25.60
                        }
                    ],
                    "pos": 2
                }
            ]
        }
    }
}

Benefits of the Enhanced Structure

The new speakerObj approach provides:

• Structured Speaker Data: Full speaker objects instead of simple strings
• Comprehensive Information: Access to titles, positions, gender, and party affiliation
• Reliable Identification: Speaker slugs ensure consistent identification across operations
• Better Performance: More efficient speaker matching and updates
• Enhanced Integration: Consistent data structure across all API endpoints
• Rich Metadata: Support for complex organizational hierarchies and roles

Document Creation Process

• This mutation updates the speaker names and information across all relevant textsegment entries.
• It creates the first level of document depth, allowing for initial processing or export.
• In the first step, the document is created with only one depth level. However, multiple depth levels are possible.
• To add more depths, you can use the updateAgendaItemById mutation to edit the depth at index 0.
• After that, follow the instructions in the next section of the documentation to continue adding further depth levels to the document.

This enhanced approach ensures that all speaker attributions are accurate with rich metadata, and the protocol is ready for downstream use or publication with comprehensive speaker information.

📚 Legacy Documentation

If you need to reference the old implementation for migration purposes, see:

Legacy Edit Speakers Documentation →

Have questions?

Still have questions? Talk to support.