docs: add examples how to use eSpeak NG as a C library

README.md

@@ -64,9 +64,10 @@ The following platforms are supported:
 
 1. [User guide](src/espeak-ng.1.ronn) provides reference and examples for command-line options.
 2. [Building guide](docs/building.md) provides info how to compile and build eSpeak NG from the source.
-3. [Index](docs/index.md) provides full list of more detailed information for contributors and developers.
-4. Look at [contribution guide](docs/contributing.md) to start your contribution.
-5. Look at [eSpeak NG roadmap](https://github.com/espeak-ng/espeak-ng/wiki/eSpeak-NG-roadmap) to participate in development of eSpeak NG.
+3. [Integration guide](docs/integration.md) provides samples how to use eSpeak NG as a library.
+4. [Index](docs/index.md) provides full list of more detailed information for contributors and developers.
+5. Look at [contribution guide](docs/contributing.md) to start your contribution.
+6. Look at [eSpeak NG roadmap](https://github.com/espeak-ng/espeak-ng/wiki/eSpeak-NG-roadmap) to participate in development of eSpeak NG.
 
 ## eSpeak Compatibility
 

docs/index.md

@@ -7,6 +7,7 @@
   - [SSML and HTML Support](markup.md)
 - [Contributor Guide](contributing.md)
   - [Building eSpeak NG](building.md)
+  - [Using eSpeak NG as a C library](integration.md)
 - Creating and Editing Languages and Voices
     - [Adding or Improving a Language](add_language.md)
     - [Text to Phoneme Translation](dictionary.md)

docs/integration.md

@@ -0,0 +1,90 @@
+#  Using eSpeak NG as a library
+
+- [Simple steps](#simple-steps)
+- [Error solutions](#error-solutions)
+- [Additional info](#additional-info)
+
+## Simple steps
+
+1. Ensure you have satisfied [building dependencies](building.md)
+
+2. To use eSpeak NG as a C library, create file `test-espeak.c` with following content:
+
+
+        #include <espeak-ng/speak_lib.h>
+        
+        espeak_AUDIO_OUTPUT output = AUDIO_OUTPUT_SYNCH_PLAYBACK;
+        char *path = NULL;
+        void* user_data;
+        unsigned int *identifier;
+        
+        int main(int argc, char* argv[]) {
+          char voicename[] = {"English"}; // Set voice by its name
+          char text[] = {"Hello world!"};
+          int buflength = 500, options = 0;
+          unsigned int position = 0, position_type = 0, end_position = 0, flags = espeakCHARS_AUTO;
+          espeak_Initialize(output, buflength, path, options);
+          espeak_SetVoiceByName(voicename);
+          printf("Saying  '%s'...\n", text);
+          espeak_Synth(text, buflength, position, position_type, end_position, flags, identifier, user_data);
+          printf("Done\n");
+          return 0;
+        }
+
+3. Compile created file with command:
+
+        gcc test-espeak.c -lespeak-ng -o test-espeak
+
+4. Run created binary with the command:
+
+        ./test-espeak
+
+## Error solutions
+
+If, during compilation, you get error like `espeak-ng/speak_lib.h: No such file or directory`,
+you may try to replace line:
+
+    #include <espeak-ng/speak_lib.h>
+
+with
+
+    #include "/your/path/to/speak_lib.h"
+
+where `/your/path/to/` is actual path, where header file is located.
+
+## Additional info
+
+Code above set library using just voice name with related [language](languages.md) to it.
+Code below shows, how to set more detailed properties of the voice (e.g. language, variant and gender):
+
+    #include <string.h>
+    #include <malloc.h>
+    #include <espeak-ng/speak_lib.h>
+    
+    espeak_AUDIO_OUTPUT output = AUDIO_OUTPUT_SYNCH_PLAYBACK;
+    char *path = NULL;
+    void* user_data;
+    unsigned int *identifier;
+    
+    int main(int argc, char* argv[] ) {
+      char text[] = {"Hello world!"};
+      int buflength = 500, options = 0;
+      unsigned int position = 0, position_type = 0, end_position = 0, flags = espeakCHARS_AUTO;
+      espeak_Initialize(output, buflength, path, options );
+      espeak_VOICE voice;
+      memset(&voice, 0, sizeof(espeak_VOICE)); // Zero out the voice first
+      const char *langNativeString = "en"; // Set voice by properties
+      voice.languages = langNativeString;
+      voice.name = "US";
+      voice.variant = 2;
+      voice.gender = 2;
+      espeak_SetVoiceByProperties(&voice);
+      printf("Saying  '%s'...\n", text);
+      espeak_Synth(text, buflength, position, position_type, end_position, flags, identifier, user_data);
+      printf("Done\n");
+      return 0;
+    }
+
+Look for details at [espeak_ng.h](https://github.com/espeak-ng/espeak-ng/blob/master/src/include/espeak-ng/espeak_ng.h) and [speak_lib.h](https://github.com/espeak-ng/espeak-ng/blob/master/src/include/espeak-ng/speak_lib.h) files.
+
+