adding java and toc entry

Author: Trevor Bye

articles/cognitive-services/Speech-Service/includes/how-to/text-to-speech-basics/text-to-speech-basics-java.md

@@ -0,0 +1,237 @@
+---
+author: trevorbye
+ms.service: cognitive-services
+ms.topic: include
+ms.date: 03/25/2020
+ms.author: trbye
+---
+
+## Prerequisites
+
+This article assumes that you have an Azure account and Speech service subscription. If you don't have an account and subscription, [try the Speech service for free](../../../get-started.md).
+
+## Install the Speech SDK
+
+Before you can do anything, you'll need to install the Speech SDK. Depending on your platform, use the following instructions:
+
+* <a href="https://docs.microsoft.com/azure/cognitive-services/speech-service/quickstarts/setup-platform?tabs=jre&pivots=programming-language-java" target="_blank">Java Runtime <span class="docon docon-navigate-external x-hidden-focus"></span></a>
+* <a href="https://docs.microsoft.com/azure/cognitive-services/speech-service/quickstarts/setup-platform?tabs=android&pivots=programming-language-java" target="_blank">Android <span class="docon docon-navigate-external x-hidden-focus"></span></a>
+
+## Import dependencies
+
+To run the examples in this article, include the following import statements at the top of your script.
+
+```java
+import com.microsoft.cognitiveservices.speech.AudioDataStream;
+import com.microsoft.cognitiveservices.speech.SpeechConfig;
+import com.microsoft.cognitiveservices.speech.SpeechSynthesizer;
+import com.microsoft.cognitiveservices.speech.SpeechSynthesisOutputFormat;
+import com.microsoft.cognitiveservices.speech.SpeechSynthesisResult;
+import com.microsoft.cognitiveservices.speech.audio.AudioConfig;
+
+import java.io.*;
+import java.util.Scanner;
+```
+
+## Create a speech configuration
+
+To call the Speech service using the Speech SDK, you need to create a [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable). This class includes information about your subscription, like your key and associated region, endpoint, host, or authorization token.
+
+> [!NOTE]
+> Regardless of whether you're performing speech recognition, speech synthesis, translation, or intent recognition, you'll always create a configuration.
+
+There are a few ways that you can initialize a [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable):
+
+* With a subscription: pass in a key and the associated region.
+* With an endpoint: pass in a Speech service endpoint. A key or authorization token is optional.
+* With a host: pass in a host address. A key or authorization token is optional.
+* With an authorization token: pass in an authorization token and the associated region.
+
+In this example, you create a [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable) using a subscription key and region. See the [region support](https://docs.microsoft.com/azure/cognitive-services/speech-service/regions#speech-sdk) page to find your region identifier. You also create some basic boilerplate code to use for the rest of this article, which you modify for different customizations.
+
+```java
+public class Program 
+{
+    public static void main(String[] args) {
+        SpeechConfig speechConfig = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+    }
+}
+```
+
+## Synthesize speech to a file
+
+Next, you create a [`SpeechSynthesizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechsynthesizer?view=azure-java-stable) object, which executes text-to-speech conversions and outputs to speakers, files, or other output streams. The [`SpeechSynthesizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechsynthesizer?view=azure-java-stable) accepts as params the [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable) object created in the previous step, and an [`AudioConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.audio.audioconfig?view=azure-java-stable) object that specifies how output results should be handled.
+
+To start, create an `AudioConfig` to automatically write the output to a `.wav` file using the `fromWavFileOutput()` static function.
+
+```java
+public static void main(String[] args) {
+    SpeechConfig speechConfig = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+    AudioConfig audioConfig = AudioConfig.fromWavFileOutput("path/to/write/file.wav");
+}
+```
+
+Next, instantiate a `SpeechSynthesizer` passing your `speechConfig` object and the `audioConfig` object as params. Then, executing speech synthesis and writing to a file is as simple as running `SpeakText()` with a string of text.
+
+```java
+public static void main(String[] args) {
+    SpeechConfig speechConfig = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+    AudioConfig audioConfig = AudioConfig.fromWavFileOutput("path/to/write/file.wav");
+
+    SpeechSynthesizer synthesizer = new SpeechSynthesizer(speechConfig, audioConfig);
+    synthesizer.SpeakText("A simple test to write to a file.");
+}
+```
+
+Run the program, and a synthesized `.wav` file is written to the location you specified. This is a good example of the most basic usage, but next you look at customizing output and handling the output response as an in-memory stream for working with custom scenarios.
+
+### Synthesize to speaker output
+
+In some cases, you may want to directly output synthesized speech directly to a speaker. To do this, instantiate the `AudioConfig` using the `fromDefaultSpeakerOutput()` static function. This outputs to the current active output device.
+
+```java
+public static void main(String[] args) {
+    SpeechConfig speechConfig = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+    AudioConfig audioConfig = AudioConfig.fromDefaultSpeakerOutput();
+
+    SpeechSynthesizer synthesizer = new SpeechSynthesizer(speechConfig, audioConfig);
+    synthesizer.SpeakText("Synthesizing directly to speaker output.");
+}
+```
+
+## Get result as an in-memory stream
+
+For many scenarios in speech application development, you likely need the resulting audio data as an in-memory stream rather than directly writing to a file. This will allow you to build custom behavior including:
+
+* Abstract the resulting byte array as a seek-able stream for custom downstream services.
+* Integrate the result with other API's or services.
+* Modify the audio data, write custom `.wav` headers, etc.
+
+It's simple to make this change from the previous example. First, remove the `AudioConfig` block, as you will manage the output behavior manually from this point onward for increased control. Then pass `null` for the `AudioConfig` in the `SpeechSynthesizer` constructor. 
+
+> ![NOTE]
+> Passing `null` for the `AudioConfig`, rather than omitting it like in the speaker output example 
+> above, will not play the audio by default on the current active output device.
+
+This time, you save the result to a [`SpeechSynthesisResult`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechsynthesisresult?view=azure-java-stable) variable. The `SpeechSynthesisResult.getAudioData()` function returns a `byte []` of the output data. You can work with this `byte []` manually, or you can use the [`AudioDataStream`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.audiodatastream?view=azure-java-stable) class to manage the in-memory stream. In this example you use the `AudioDataStream.fromResult()` static function to get a stream from the result.
+
+```java
+public static void main(String[] args) {
+    SpeechConfig speechConfig = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+    SpeechSynthesizer synthesizer = new SpeechSynthesizer(speechConfig, null);
+    
+    SpeechSynthesisResult result = synthesizer.SpeakText("Getting the response as an in-memory stream.");
+    AudioDataStream stream = AudioDataStream.fromResult(result);
+    System.out.print(stream.getStatus());
+}
+```
+
+From here you can implement any custom behavior using the resulting `stream` object.
+
+## Customize audio format
+
+The following section shows how to customize audio output attributes including:
+
+* Audio file type
+* Sample-rate
+* Bit-depth
+
+To change the audio format, you use the `setSpeechSynthesisOutputFormat()` function on the `SpeechConfig` object. This function expects an `enum` of type [`SpeechSynthesisOutputFormat`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechsynthesisoutputformat?view=azure-java-stable), which you use to select the output format. See the reference docs for a [list of audio formats](https://docs.microsoft.com/dotnet/api/microsoft.cognitiveservices.speech.speechsynthesisoutputformat?view=azure-dotnet) that are available.
+
+There are various options for different file types depending on your requirements. Note that by definition, raw formats like `Raw24Khz16BitMonoPcm` do not include audio headers. Use raw formats only when you know your downstream implementation can decode a raw bitstream, or if you plan on manually building headers based on bit-depth, sample-rate, number of channels, etc.
+
+In this example, you specify a high-fidelity RIFF format `Riff24Khz16BitMonoPcm` by setting the `SpeechSynthesisOutputFormat` on the `SpeechConfig` object. Similar to the example in the previous section, you use [`AudioDataStream`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.audiodatastream?view=azure-java-stable) to get an in-memory stream of the result, and then write it to a file.
+
+```java
+public static void main(String[] args) {
+    SpeechConfig speechConfig = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+
+    // set the output format
+    speechConfig.setSpeechSynthesisOutputFormat(SpeechSynthesisOutputFormat.Riff24Khz16BitMonoPcm);
+
+    SpeechSynthesizer synthesizer = new SpeechSynthesizer(speechConfig, null);
+    SpeechSynthesisResult result = synthesizer.SpeakText("Customizing audio output format.");
+    AudioDataStream stream = AudioDataStream.fromResult(result);
+    stream.saveToWavFile("path/to/write/file.wav");
+}
+```
+
+Running your program again will write a `.wav` file to the specified path.
+
+## Use SSML to customize speech characteristics
+
+Speech Synthesis Markup Language (SSML) allows you to fine-tune the pitch, pronunciation, speaking rate, volume, and more of the text-to-speech output by submitting your requests from an XML schema. This section shows a few practical usage examples, but for a more detailed guide, see the [SSML how-to article](../../../speech-synthesis-markup.md).
+
+To start using SSML for customization, you make a simple change that switches the voice.
+First, create a new XML file for the SSML config in your root project directory, in this example `ssml.xml`. The root element is always `<speak>`, and wrapping the text in a `<voice>` element allows you to change the voice using the `name` param. This example changes the voice to a male English (UK) voice. Note that this voice is a **standard** voice, which has different pricing and availability than **neural** voices. See the [full list](https://docs.microsoft.com/azure/cognitive-services/speech-service/language-support#standard-voices) of supported **standard** voices.
+
+```xml
+<speak version="1.0" xmlns="https://www.w3.org/2001/10/synthesis" xml:lang="en-US">
+  <voice name="en-GB-George-Apollo">
+    When you're on the motorway, it's a good idea to use a sat-nav.
+  </voice>
+</speak>
+```
+
+Next, you need to change the speech synthesis request to reference your XML file. The request is mostly the same, but instead of using the `SpeakText()` function, you use `SpeakSsml()`. This function expects an XML string, so first you create a function to load an XML file and return it as a string.
+
+```java
+private static String xmlToString(String filePath) {
+    File file = new File(filePath);
+    StringBuilder fileContents = new StringBuilder((int)file.length());
+
+    try (Scanner scanner = new Scanner(file)) {
+        while(scanner.hasNextLine()) {
+            fileContents.append(scanner.nextLine() + System.lineSeparator());
+        }
+        return fileContents.toString().trim();
+    } catch (FileNotFoundException ex) {
+        return "File not found.";
+    }
+}
+```
+
+From here, the result object is exactly the same as previous examples.
+
+```java
+public static void main(String[] args) {
+    SpeechConfig speechConfig = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+    SpeechSynthesizer synthesizer = new SpeechSynthesizer(speechConfig, null);
+
+    String ssml = xmlToString("ssml.xml");
+    SpeechSynthesisResult result = synthesizer.SpeakSsml(ssml);
+    AudioDataStream stream = AudioDataStream.fromResult(result);
+    stream.saveToWavFile("path/to/write/file.wav");
+}
+```
+
+The output works, but there a few simple additional changes you can make to help it sound more natural. The overall speaking speed is a little too fast, so we'll add a `<prosody>` tag and reduce the speed to **90%** of the default rate. Additionally, the pause after the comma in the sentence is a little too short and unnatural sounding. To fix this issue, add a `<break>` tag to delay the speech, and set the time param to **200ms**. Re-run the synthesis to see how these customizations affected the output.
+
+```xml
+<speak version="1.0" xmlns="https://www.w3.org/2001/10/synthesis" xml:lang="en-US">
+  <voice name="en-GB-George-Apollo">
+    <prosody rate="0.9">
+      When you're on the motorway,<break time="200ms"/> it's a good idea to use a sat-nav.
+    </prosody>
+  </voice>
+</speak>
+```
+
+### Neural voices
+
+Neural voices are speech synthesis algorithms powered by deep neural networks. When using a neural voice, synthesized speech is nearly indistinguishable from the human recordings. With the human-like natural prosody and clear articulation of words, neural voices significantly reduce listening fatigue when users interact with AI systems.
+
+To switch to a neural voice, change the `name` to one of the [neural voice options](https://docs.microsoft.com/azure/cognitive-services/speech-service/language-support#neural-voices). Then, add an XML namespace for `mstts`, and wrap your text in the `<mstts:express-as>` tag. Use the `style` param to customize the speaking style. This example uses `cheerful`, but try setting it to `customerservice` or `chat` to see the difference in speaking style.
+
+> [!IMPORTANT]
+> Neural voices are **only** supported for Speech resources created in *East US*, *South East Asia*, and *West Europe* regions.
+
+```xml
+<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="https://www.w3.org/2001/mstts" xml:lang="en-US">
+  <voice name="en-US-AriaNeural">
+    <mstts:express-as style="cheerful">
+      This is awesome!
+    </mstts:express-as>
+  </voice>
+</speak>
+```

articles/cognitive-services/Speech-Service/text-to-speech-basics.md

@@ -35,7 +35,7 @@ In this article, you learn common design patterns for doing text-to-speech synth
 ::: zone-end
 
 ::: zone pivot="programming-language-java"
-[!INCLUDE [Java Basics include]()]
+[!INCLUDE [Java Basics include](includes/how-to/text-to-speech-basics/text-to-speech-basics-java.md)]
 ::: zone-end
 
 ::: zone pivot="programming-language-python"

articles/cognitive-services/Speech-Service/toc.yml

@@ -113,6 +113,8 @@
       items:
         - name: What is text-to-speech?
           href: text-to-speech.md
+        - name: Text-to-speech basics
+          href: text-to-speech-basics.md
     - name: Quickstart
       items:
         - name: Synthesize speech to a speaker