Rename Speakers

Rename Speakers in Text Segments

The following description is only necessary for protocol type politics. If you created a protocol type of summary your next and final call would be the getResults query.

Once the protocol has finished processing (status = true from getProtocolBySlug), the next step is to rename speakers in all text segments. This ensures that the final document has accurate speaker attributions.

Understanding the Data

For a deeper understanding of the data see the getProtocolBySlug tutorial.

GraphQL Mutation

mutation RenameSpeakerInTextsegment(
  $protocolSlug: String!
  $speakerList: [SpeakerDataInput]!
) {
  renameSpeakerInTextsegment(
    protocolSlug: $protocolSlug
    speakerList: $speakerList
  ) {
    success
    nextSteps
  }
}

Mutation Variables For each speaker, provide a SpeakerDataInput object with the oldSlug (existing speaker identifier) and updated speaker details:

{
  "protocolSlug": "PROTOCOL_SLUG",
  "speakerList": [
    {
      "oldSlug": "SPEAKER_SLUG",
      "gender": "m",
      "givenName": "Thomas",
      "familyName": "Müller",
      "party": "",
      "preTitle": "",
      "postTitle": "",
      "posShort": "",
      "posLong": "",
      "systemId": ""
    },
    {
      "oldSlug": "SPEAKER_SLUG",
      "gender": "m",
      "givenName": "Max",
      "familyName": "Mustermann",
      "party": "",
      "preTitle": "",
      "postTitle": "",
      "posShort": "",
      "posLong": "",
      "systemId": ""
    }
  ]
}

Using specialCase for Background Noise or Non-Speaker Events

The specialCase: true flag can be set on any speaker entry. When used:

• Only givenName is used as the display name — all other fields are ignored.
• The speaker is excluded from summary output.

This is useful for labeling segments that are not actual speakers — for example background noise or interruptions:

{
  "oldSlug": "spk-abc123",
  "specialCase": true,
  "givenName": "Hintergrundgeräusch"
}

✅ Tip: Use the speakerList and summaryPerSpeakerList from getProtocolBySlug to automatically build this array. You can also use speakerSuggestion for recommended names.

Example JavaScript Implementation

import axios from "axios";

export const RENAME_SPEAKER_MUTATION = `...`;

async function renameSpeakers(protocolSlug, speakerList) {
  try {
    const response = await axios({
      method: "POST",
      url: "https://api-v2.speechmind.com/external/v2/graphql",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.SPEECHMIND_API_KEY,
      },
      data: JSON.stringify({
        query: RENAME_SPEAKER_MUTATION,
        variables: { protocolSlug, speakerList },
      }),
    });

    const data = response.data.data.renameSpeakerInTextsegment;

    if (data.success) {
      console.log("✔️ Speakers successfully renamed!");
      console.log("Next steps:", data.nextSteps);
    } else {
      console.log("❌ Failed to rename speakers");
    }
  } catch (error) {
    console.error("Error renaming speakers:", error);
  }
}

// Example usage
const protocolSlug = "PROTOCOL_SLUG";
const speakerList = [
  { oldSlug: "SPEAKER_SLUG", gender: "m", givenName: "Thomas", familyName: "Müller", party: "", preTitle: "", postTitle: "", posShort: "", posLong: "", systemId: "" },
  { oldSlug: "SPEAKER_SLUG", gender: "m", givenName: "Max", familyName: "Mustermann", party: "", preTitle: "", postTitle: "", posShort: "", posLong: "", systemId: "" }
];

renameSpeakers(protocolSlug, speakerList);

Next Steps

After renaming speakers, the text segments are updated and all the detail depths of the protocol will be created. This process can take some time based on the duration of the audio file and the resulting amount of text.

Next step would be calling the getResults query.

Have questions?

Still have questions? Talk to support.