From aec8baf093a8f23188b994680da1f117bd033687 Mon Sep 17 00:00:00 2001 From: Valdis Vitolins Date: Tue, 21 Jul 2020 16:46:12 +0300 Subject: [PATCH] docs: add examples how to use eSpeak NG as a C library --- README.md | 7 ++-- docs/index.md | 1 + docs/integration.md | 90 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+), 3 deletions(-) create mode 100644 docs/integration.md diff --git a/README.md b/README.md index d3bc8aae..8a148929 100644 --- a/README.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index 30d82b2b..75c97fd8 100644 --- a/docs/index.md +++ b/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) diff --git a/docs/integration.md b/docs/integration.md new file mode 100644 index 00000000..e49ccc4f --- /dev/null +++ b/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_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 + +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 + #include + #include + + 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. + +