快速入門：多裝置對話

發行項
09/04/2024

在本快速入門中，您將了解如何使用語音 SDK 來建立具有翻譯支援的新多裝置交談，以及如何加入現有交談。

注意

適用於 JAVA、JavaScript、Objective-C 和 Swift 的語音 SDK 支援多裝置對話，但目前尚未提供相對應的指南。

您可以在 GitHub 上檢視或下載所有語音 SDK C# 範例。

必要條件

開始之前，請務必：

新增範例程式碼

開啟 Program.cs，並以下列程式碼取代其中的所有程式碼：

using Microsoft.CognitiveServices.Speech;
using Microsoft.CognitiveServices.Speech.Audio;
using Microsoft.CognitiveServices.Speech.Transcription;
using System;
using System.Threading.Tasks;

namespace HelloWorld
{
    class Program
    {
        static async Task Main(string[] args)
        {
            await CreateConversationAsync();
        }

        static async Task CreateConversationAsync()
        {
            // Replace these values with the details of your Cognitive Speech subscription
            string subscriptionKey = "YourSubscriptionKey";

            // Replace below with your region identifier from here: https://aka.ms/speech/sdkregion
            string region = "YourServiceRegion";

            // Sets source and target languages.
            // Replace with the languages of your choice, from list found here: https://aka.ms/speech/sttt-languages
            string fromLanguage = "en-US";
            string toLanguage = "de";

            // Set this to the display name you want for the conversation host
            string displayName = "The host";

            // Create the task completion source that will be used to wait until the user presses Ctrl + C
            var completionSource = new TaskCompletionSource<bool>();

            // Register to listen for Ctrl + C
            Console.CancelKeyPress += (s, e) =>
            {
                completionSource.TrySetResult(true);
                e.Cancel = true; // don't terminate the current process
            };

            // Create an instance of the speech translation config
            var config = SpeechTranslationConfig.FromSubscription(subscriptionKey, region);
            config.SpeechRecognitionLanguage = fromLanguage;
            config.AddTargetLanguage(toLanguage);

            // Create the conversation
            using (var conversation = await Conversation.CreateConversationAsync(config).ConfigureAwait(false))
            {
                // Start the conversation so the host user and others can join
                await conversation.StartConversationAsync().ConfigureAwait(false);

                // Get the conversation ID. It will be up to your scenario to determine how this is shared with other participants.
                string conversationId = conversation.ConversationId;
                Console.WriteLine($"Created '{conversationId}' conversation");

                // At this point, you can use the conversation object to manage the conversation. 
                // For example, to mute everyone else in the room you can call this method:
                await conversation.MuteAllParticipantsAsync().ConfigureAwait(false);

                // Configure which audio source you want to use. If you are using a text only language, you 
                // can use the other overload of the constructor that takes no arguments
                var audioConfig = AudioConfig.FromDefaultMicrophoneInput();
                using (var conversationTranslator = new ConversationTranslator(audioConfig))
                {
                    // You should connect all the event handlers you need at this point
                    conversationTranslator.SessionStarted += (s, e) =>
                    {
                        Console.WriteLine($"Session started: {e.SessionId}");
                    };
                    conversationTranslator.SessionStopped += (s, e) =>
                    {
                        Console.WriteLine($"Session stopped: {e.SessionId}");
                    };
                    conversationTranslator.Canceled += (s, e) =>
                    {
                        switch (e.Reason)
                        {
                            case CancellationReason.EndOfStream:
                                Console.WriteLine($"End of audio reached");
                                break;

                            case CancellationReason.Error:
                                Console.WriteLine($"Canceled due to error. {e.ErrorCode}: {e.ErrorDetails}");
                                break;
                        }
                    };
                    conversationTranslator.ConversationExpiration += (s, e) =>
                    {
                        Console.WriteLine($"Conversation will expire in {e.ExpirationTime.TotalMinutes} minutes");
                    };
                    conversationTranslator.ParticipantsChanged += (s, e) =>
                    {
                        Console.Write("The following participant(s) have ");
                        switch (e.Reason)
                        {
                            case ParticipantChangedReason.JoinedConversation:
                                Console.Write("joined");
                                break;

                            case ParticipantChangedReason.LeftConversation:
                                Console.Write("left");
                                break;

                            case ParticipantChangedReason.Updated:
                                Console.Write("been updated");
                                break;
                        }

                        Console.WriteLine(":");

                        foreach (var participant in e.Participants)
                        {
                            Console.WriteLine($"\t{participant.DisplayName}");
                        }
                    };
                    conversationTranslator.TextMessageReceived += (s, e) =>
                    {
                        Console.WriteLine($"Received an instant message from '{e.Result.ParticipantId}': '{e.Result.Text}'");
                        foreach (var entry in e.Result.Translations)
                        {
                            Console.WriteLine($"\tTranslated into '{entry.Key}': '{entry.Value}'");
                        }
                    };
                    conversationTranslator.Transcribed += (s, e) =>
                    {
                        Console.WriteLine($"Received a transcription from '{e.Result.ParticipantId}': '{e.Result.Text}'");
                        foreach (var entry in e.Result.Translations)
                        {
                            Console.WriteLine($"\tTranslated into '{entry.Key}': '{entry.Value}'");
                        }
                    };
                    conversationTranslator.Transcribing += (s, e) =>
                    {
                        Console.WriteLine($"Received a partial transcription from '{e.Result.ParticipantId}': '{e.Result.Text}'");
                        foreach (var entry in e.Result.Translations)
                        {
                            Console.WriteLine($"\tTranslated into '{entry.Key}': '{entry.Value}'");
                        }
                    };

                    // Enter the conversation to start receiving events
                    await conversationTranslator.JoinConversationAsync(conversation, displayName).ConfigureAwait(false);

                    // You can now send an instant message to all other participants in the room
                    await conversationTranslator.SendTextMessageAsync("The instant message to send").ConfigureAwait(false);

                    // If specified a speech to text language, you can start capturing audio
                    await conversationTranslator.StartTranscribingAsync().ConfigureAwait(false);
                    Console.WriteLine("Started transcribing. Press Ctrl + c to stop");

                    // At this point, you should start receiving transcriptions for what you are saying using the default microphone. Press Ctrl+c to stop audio capture
                    await completionSource.Task.ConfigureAwait(false);

                    // Stop audio capture
                    await conversationTranslator.StopTranscribingAsync().ConfigureAwait(false);

                    // Leave the conversation. After this you will no longer receive events
                    await conversationTranslator.LeaveConversationAsync().ConfigureAwait(false);
                }

                // End the conversation
                await conversation.EndConversationAsync().ConfigureAwait(false);

                // Delete the conversation. Any other participants that are still in the conversation will be removed
                await conversation.DeleteConversationAsync().ConfigureAwait(false);
            }
        }
    }
}

在相同檔案中，以您的 Cognitive Speech 訂用帳戶金鑰取代 YourSubscriptionKey 字串。
將字串 YourServiceRegion 取代為與您的訂用帳戶相關聯的區域。
從功能表列中，選擇 [檔案]>[全部儲存]。

建置並執行應用程式以建立新的交談

從功能表列中，選取 [建置]>[建置方案] 來建置應用程式。程式碼現在應該可以編譯，而且不會出現任何錯誤。
選擇 [偵錯]>[開始偵錯] (或按 F5) 以啟動 helloworld 應用程式。
一旦看到 Started transcribing 訊息出現，您就可以開始說話。當您說話時，您會看到文字記錄出現。
- 如果您與其他人共用交談程式碼，而且這些人加入交談，您也會看到他們的文字記錄。
說完之後，請按 Ctrl+C 來停止音訊擷取，並結束交談。

建置並執行應用程式以加入現有交談

複製下列函式並貼到您的 Program.cs 中：

static async Task JoinConversationAsync(string conversationId)
{
    // Set this to the display name you want for the participant
    string displayName = "participant";

    // Set the speech to text, or text language you want to use
    string language = "en-US";

    // Create the task completion source that will be used to wait until the user presses Ctrl + c
    var completionSource = new TaskCompletionSource<bool>();

    // Register to listen for Ctrl+C
    Console.CancelKeyPress += (s, e) =>
    {
        completionSource.TrySetResult(true);
        e.Cancel = true; // don't terminate the current process
    };

    // As a participant, you don't need to specify any subscription key, or region. You can directly create
    // the conversation translator object
    var audioConfig = AudioConfig.FromDefaultMicrophoneInput();
    using (var conversationTranslator = new ConversationTranslator(audioConfig))
    {
        // Register for any events you are interested here. For now let's just register for
        // transcription, and instant message events
        conversationTranslator.TextMessageReceived += (s, e) =>
        {
            Console.WriteLine($"Received an instant message from '{e.Result.ParticipantId}': '{e.Result.Text}'");
            foreach (var entry in e.Result.Translations)
            {
                Console.WriteLine($"\tTranslated into '{entry.Key}': '{entry.Value}'");
            }
        };
        conversationTranslator.Transcribed += (s, e) =>
        {
            Console.WriteLine($"Received a transcription from '{e.Result.ParticipantId}': '{e.Result.Text}'");
            foreach (var entry in e.Result.Translations)
            {
                Console.WriteLine($"\tTranslated into '{entry.Key}': '{entry.Value}'");
            }
        };
        conversationTranslator.Transcribing += (s, e) =>
        {
            Console.WriteLine($"Received a partial transcription from '{e.Result.ParticipantId}': '{e.Result.Text}'");
            foreach (var entry in e.Result.Translations)
            {
                Console.WriteLine($"\tTranslated into '{entry.Key}': '{entry.Value}'");
            }
        };

        // To start receiving events, you will need to join the conversation
        await conversationTranslator.JoinConversationAsync(conversationId, displayName, language).ConfigureAwait(false);

        // You can now send an instant message
        await conversationTranslator.SendTextMessageAsync("Message from participant").ConfigureAwait(false);

        // Start capturing audio if you specified a speech to text language
        await conversationTranslator.StartTranscribingAsync().ConfigureAwait(false);
        Console.WriteLine("Started transcribing. Press Ctrl-C to stop");

        // At this point, you should start receiving transcriptions for what you are saying using
        // the default microphone. Press Ctrl+C to stop audio capture
        await completionSource.Task.ConfigureAwait(false);

        // Stop audio capture
        await conversationTranslator.StopTranscribingAsync().ConfigureAwait(false);

        // Leave the conversation. You will stop receiving events after this
        await conversationTranslator.LeaveConversationAsync().ConfigureAwait(false);
    }
}

使用下列內容取代 public static async Task Main(string[] args) 函式中的 CreateConversationAsync();：
```
// Set this to the conversation you want to join
JoinConversationAsync("YourConversationId");
```

您必須建立可加入的交談：
1. 啟動瀏覽器並瀏覽至：https://translator.microsoft.com。
2. 選取 [開始交談]。
3. 使用任何可用的選項來登入。
4. 輸入名稱 (例如「主機」)。
5. 選取語言 (例如「英文」)。
6. 選取 Enter 按鈕。
7. 請注意頁面頂端的交談程式碼。
提示

如果您使用網頁上的 [複製] 按鈕，請務必在開始時移除 translate.it/。您只需要 5 個字元的對話識別碼 (範例：ABCDE)。

返回 Visual Studio，並將字串 YourConversationId 取代為您在上一個步驟中建立的交談識別碼。
從功能表列中，選取 [建置]>[建置方案] 來建置應用程式。程式碼現在應該可以編譯，而且不會出現任何錯誤。
選擇 [偵錯]>[開始偵錯] (或按 F5) 以啟動 helloworld 應用程式。
一旦看到 Started transcribing 訊息出現，您就可以開始說話。當您說話時，您會看到文字記錄出現。
- 如果您返回瀏覽器，則應該也會在說話時看到文字記錄出現在該處。
說完之後，請按 Ctrl+C 來停止音訊擷取，並結束交談。
返回瀏覽器，並使用右上角的 [結束] 按鈕來結束交談。

後續步驟

探索 GitHub 上的 C# 範例 \(英文\)

您可以在 GitHub 上檢視或下載所有語音 SDK C++ 範例。

必要條件

開始之前，請務必：

新增範例程式碼

從 Visual Studio 開啟來源檔案 helloworld.cpp。

使用下列程式碼片段取代所有程式碼：

#include "pch.h"

#define WIN32_LEAN_AND_MEAN
#include <Windows.h>

#include <iostream>
#include <thread>
#include <future>
#include <string>
#include <speechapi_cxx.h>

using namespace std::chrono_literals;
using namespace Microsoft::CognitiveServices::Speech;
using namespace Microsoft::CognitiveServices::Speech::Audio;
using namespace Microsoft::CognitiveServices::Speech::Transcription;

// Create a promise we will set when the user presses Ctrl-C
std::promise<bool> promise;
// Create the future we will use to wait for the promise to be fulfilled
std::future<bool> future = promise.get_future();

void StartNewConversation()
{
    // Set these
    std::string subscriptionKey("YourSubscriptionKey");

    // Replace below with your own region identifier from here: https://aka.ms/speech/sdkregion
    std::string region("YourServiceRegion");

    std::string speechLanguage("en-US");

    // Create the conversation object you'll need to manage the conversation
    auto speechConfig = SpeechConfig::FromSubscription(subscriptionKey, region);
    speechConfig->SetSpeechRecognitionLanguage(speechLanguage);
    auto conversation = Conversation::CreateConversationAsync(speechConfig).get();

    // Start the conversation so you and others can join
    conversation->StartConversationAsync().get();

    // Get the conversation ID. It will be up to your scenario to determine how this is shared with other participants.
    std::cout << "Created conversation: " << conversation->GetConversationId() << std::endl;

    // You can now call various commands to manage the room. For example:
    conversation->MuteAllParticipantsAsync().get();

    // Create the conversation translator you'll need to send audio, send IMs, and receive conversation events
    auto audioConfig = AudioConfig::FromDefaultMicrophoneInput();
    auto conversationTranslator = ConversationTranslator::FromConfig(audioConfig);

    // Add any event handlers
    conversationTranslator->SessionStarted += [](const SessionEventArgs& args)
    {
        std::cout << "Session started " << args.SessionId << std::endl;
    };
    conversationTranslator->SessionStopped += [](const SessionEventArgs& args)
    {
        std::cout << "Session stopped " << args.SessionId << std::endl;
    };
    conversationTranslator->Canceled += [](const ConversationTranslationCanceledEventArgs& args)
    {
        switch (args.Reason)
        {
            case CancellationReason::EndOfStream:
                std::cout << "End of audio reached" << std::endl;
                break;

            case CancellationReason::Error:
                std::cout << "Canceled due to error. " << (long)args.ErrorCode << ": " << args.ErrorDetails << std::endl;
                break;
        }
    };
    conversationTranslator->ConversationExpiration += [](const ConversationExpirationEventArgs& args)
    {
        std::cout << "Conversation will expire in " << args.ExpirationTime.count() << " minutes" << std::endl;
    };
    conversationTranslator->ParticipantsChanged += [](const ConversationParticipantsChangedEventArgs& args)
    {
        std::cout << "The following participant(s) have ";
        switch (args.Reason)
        {
            case ParticipantChangedReason::JoinedConversation:
                std::cout << "joined";
                break;

            case ParticipantChangedReason::LeftConversation:
                std::cout << "left";
                break;

            case ParticipantChangedReason::Updated:
                std::cout << "been updated";
                break;
        }

        std::cout << ":" << std::endl;

        for(std::shared_ptr<Participant> participant : args.Participants)
        {
            std::cout << "\t" << participant->DisplayName << std::endl;
        }
    };
    conversationTranslator->Transcribing += [](const ConversationTranslationEventArgs& args)
    {
        std::cout << "Received a partial transcription from " << args.Result->ParticipantId << ": " << args.Result->Text << std::endl;
        for (const auto& entry : args.Result->Translations)
        {
            std::cout << "\t" << entry.first << ": " << entry.second << std::endl;
        }
    };
    conversationTranslator->Transcribed += [](const ConversationTranslationEventArgs& args)
    {
        std::cout << "Received a transcription from " << args.Result->ParticipantId << ": " << args.Result->Text << std::endl;
        for (const auto& entry : args.Result->Translations)
        {
            std::cout << "\t" << entry.first << ": " << entry.second << std::endl;
        }
    };
    conversationTranslator->TextMessageReceived += [](const ConversationTranslationEventArgs& args)
    {
        std::cout << "Received an instant message from " << args.Result->ParticipantId << ": " << args.Result->Text << std::endl;
        for (const auto& entry : args.Result->Translations)
        {
            std::cout << "\t" << entry.first << ": " << entry.second << std::endl;
        }
    };

    // Join the conversation so you can start receiving events
    conversationTranslator->JoinConversationAsync(conversation, "Test Host").get();

    // Send an instant message
    conversationTranslator->SendTextMessageAsync("This is a short test message").get();

    // Start sending audio
    conversationTranslator->StartTranscribingAsync().get();
    std::cout << "Started transcribing. Press Ctrl + C to stop" << std::endl;
    future.get(); // wait for Ctrl - C to be pressed

    // Stop audio capture
    conversationTranslator->StopTranscribingAsync().get();

    // Leave the conversation. You will stop receiving events
    conversationTranslator->LeaveConversationAsync().get();

    // Once you are done, remember to delete the conversation.
    conversation->EndConversationAsync().get(); // You will not be able to rejoin after this
    conversation->DeleteConversationAsync().get(); // All participants still in the room will be ejected
}

int main()
{
    // Register a handler for the Ctrl - C callback
    SetConsoleCtrlHandler(
        [](DWORD dwCtrlType) -> BOOL
        {
            if (dwCtrlType == CTRL_C_EVENT)
            {
                // Signal that the user has pressed ctrl + C
                promise.set_value(true);
                return TRUE;
            }

            return FALSE;
        },
        TRUE);

    StartNewConversation();
}

在相同檔案中，以您的訂用帳戶金鑰取代 YourSubscriptionKey 字串。
將字串 YourServiceRegion 取代為與您的訂用帳戶相關聯的區域。
從功能表列中，選擇 [檔案]>[全部儲存]。

建置並執行應用程式以建立新的交談

從功能表列中，選取 [建置]>[建置方案] 來建置應用程式。程式碼現在應該可以編譯，而且不會出現任何錯誤。
選擇 [偵錯]>[開始偵錯] (或按 F5) 以啟動 helloworld 應用程式。
一旦看到 Started transcribing 訊息出現，您就可以開始說話。當您說話時，您會看到文字記錄出現
- 如果您與其他人共用交談程式碼，而且這些人加入交談，您也會看到他們的文字記錄。
說完之後，請按下鍵盤上的 Ctrl+C 來停止音訊擷取。

注意

您可能會看到來自 Visual Studio 關於例外狀況的訊息，如下所示：Exception thrown at 0x76EB90BF (KernelBase.dll) in helloworld.exe: 0x40010005: Control-C. 您可以安全地忽略這些訊息。

按 F5 繼續。

建置並執行應用程式以加入現有交談

複製下列函式並貼到 helloworld.cpp 中的 int main() 函式正前方：

void JoinExistingConversation(const std::string& conversationId)
{
    std::string speechLanguage("en-US");

    // You'll now need to create a ConversationTranslator to send audio, send IMs, and receive conversation events
    auto audioConfig = AudioConfig::FromDefaultMicrophoneInput();
    auto conversationTranslator = ConversationTranslator::FromConfig(audioConfig);

    // Attach event handlers here. For example:
    conversationTranslator->Transcribing += [](const ConversationTranslationEventArgs& args)
    {
        std::cout << "Received a partial transcription from " << args.Result->ParticipantId << ": " << args.Result->Text << std::endl;
        for (const auto& entry : args.Result->Translations)
        {
            std::cout << "\t" << entry.first << ": " << entry.second << std::endl;
        }
    };
    conversationTranslator->Transcribed += [](const ConversationTranslationEventArgs& args)
    {
        std::cout << "Received a transcription from " << args.Result->ParticipantId << ": " << args.Result->Text << std::endl;
        for (const auto& entry : args.Result->Translations)
        {
            std::cout << "\t" << entry.first << ": " << entry.second << std::endl;
        }
    };
    conversationTranslator->TextMessageReceived += [](const ConversationTranslationEventArgs& args)
    {
        std::cout << "Received an instant message from " << args.Result->ParticipantId << ": " << args.Result->Text << std::endl;
        for (const auto& entry : args.Result->Translations)
        {
            std::cout << "\t" << entry.first << ": " << entry.second << std::endl;
        }
    };

    // Join the conversation
    conversationTranslator->JoinConversationAsync(conversationId, "participant", speechLanguage).get();

    // Start sending audio
    conversationTranslator->StartTranscribingAsync().get();
    std::cout << "Started transcribing. Press Ctrl + C to stop" << std::endl;
    future.get(); // wait for Ctrl - C to be pressed

    // Stop audio capture
    conversationTranslator->StopTranscribingAsync().get();

    // Once you are done, leave the conversation
    conversationTranslator->LeaveConversationAsync().get();
}

使用下列內容取代 int main() 函式中的 StartNewConversation();：

// Set this to the conversation you want to join
JoinExistingConversation("YourConversationId");

您必須建立可加入的交談：
1. 啟動瀏覽器並瀏覽至：https://translator.microsoft.com。
2. 選取 [開始交談]。
3. 使用任何可用的選項來登入。
4. 輸入名稱 (例如「主機」)。
5. 選取語言 (例如「英文」)。
6. 選取 Enter 按鈕。
7. 請注意頁面頂端的交談程式碼。
提示

如果您使用網頁上的 [複製] 按鈕，請務必在開始時移除 translate.it/。您只需要 5 個字元的對話識別碼 (範例：ABCDE)。

返回 Visual Studio，並將 int main() 函式中的 YourConversationId 取代為上一個步驟中的交談識別碼。
從功能表列中，選取 [建置]>[建置方案] 來建置應用程式。這應該會編譯程式碼，而且不會出現任何錯誤。
選擇 [偵錯]>[開始偵錯] (或按 F5) 以啟動 helloworld 應用程式。
一旦看到 Started transcribing 訊息出現，您就可以開始說話。當您說話時，您會看到文字記錄出現。
- 如果您返回瀏覽器，則應該也會在說話時看到文字記錄出現在該處。
說完之後，請按 Ctrl+C 來停止音訊擷取，並結束交談。

注意

您可能會看到來自 Visual Studio 關於例外狀況的訊息，如下所示：Exception thrown at 0x76EB90BF (KernelBase.dll) in helloworld.exe: 0x40010005: Control-C. 您可以安全地忽略這些訊息。

按 F5 繼續。
返回瀏覽器，並使用右上角的 [結束] 按鈕來結束交談。

下一步

探索 GitHub 上的 C++ 範例 \(英文\)

共用方式為

快速入門：多裝置對話

必要條件

新增範例程式碼

建置並執行應用程式以建立新的交談

建置並執行應用程式以加入現有交談

後續步驟

必要條件

新增範例程式碼

建置並執行應用程式以建立新的交談

建置並執行應用程式以加入現有交談

下一步

意見反應

其他資源