Table of Contents:

Welcome To OpenEars
Getting Started With OpenEars
Configuring Your App For OpenEars
Using OpenEars In Your App
Support/FAQ

Frequently Asked Questions/Support

If you have trouble with some aspect of using OpenEars and you have carefully re-read the documents and examined the example app without it helping, you can ask a question in the OpenEars forum (please turn on OPENEARSLOGGING and — if the issue relates to recognition — VERBOSEPOCKETSPHINX in OpenEarsConfig.h before posting an issue so we have some information to troubleshoot from). Free private email support is not given for OpenEars, but you can purchase a support incident if you would like to discuss a question via private email.

Please note that the #1 issue developers experience when configuring OpenEars is not using AudioSessionManager as required, so if your issue relates to sound or sound levels or recognition starting or not starting, please read up on the AudioSessionManager here. Not using AudioSessionManager or not using as it is documented will cause all kinds of issues, including too-quiet voices, speech or listening not resuming after various events or only running once, decreased recognition quality, etc. It’s very easy to use, just check the linked documentation.

FAQ

 

[TOP]

Q: I’m making changes in OpenEarsConfig.h and/or OpenEarsVoiceConfig.h in my own app and it’s having no effect.
A: Please make absolutely sure that when you are dragging files into your own app to get it OpenEars-ready, you are always using the settings shown in the image at the top of this page. If you have the “Copy items into destination group’s folder” checkbox checked, your configuration options will not be seen by the OpenEars library. If you are sure this was done correctly, you can also attempt to clean your project as explained here.

[TOP]

Q: There are a bunch of warnings after I compile and it’s annoying.

A: Yup, there are a few warnings in the static library from the dependencies. My approach is to change as little as possible in any of the codebases that OpenEars links to in order to avoid unintended consequences. [TOP]

[TOP]

Q: I got a ton of errors after running ./InstallOpenEars.pl along the lines of:

Don’t have permission to renamecmu_us_awb_cg_durmodel.cDon’t have permission to renamecmu_us_awb_cg_durmodel.hDon’t have permission to renamecmu_us_awb_cg_f0_trees.cDon’t have permission to renamecmu_us_awb_cg_f0_trees.hDon’t have permission to renamecmu_us_awb_cg_phonestate.cDon’t have permission to renamecmu_us_awb_cg_single_mcep_trees.cDon’t have permission to renamecmu_us_awb_cg_single_mcep_trees.hDon’t have permission to renamecmu_us_awb_cg_single_params.cDon’t have permission to renamecmu_us_awb_cg.cDon’t have permission to renamecmu_us_awb.cDon’t have permission to renamecmu_us_rms_cg_durmodel.cDon’t have permission to renamecmu_us_rms_cg_durmodel.hDon’t have permission to renamecmu_us_rms_cg_f0_trees.cDon’t have permission to renamecmu_us_rms_cg_f0_trees.hDon’t have permission to renamecmu_us_rms_cg_phonestate.cDon’t have permission to renamecmu_us_rms_cg_single_mcep_trees.cDon’t have permission to renamecmu_us_rms_cg_single_mcep_trees.hDon’t have permission to renamecmu_us_rms_cg_single_params.cDon’t have permission to renamecmu_us_rms_cg.cDon’t have permission to renamecmu_us_rms.cDon’t have permission to renamecmu_us_slt_cg_durmodel.cDon’t have permission to renamecmu_us_slt_cg_durmodel.hDon’t have permission to renamecmu_us_slt_cg_f0_trees.cDon’t have permission to renamecmu_us_slt_cg_f0_trees.hDon’t have permission to renamecmu_us_slt_cg_phonestate.cDon’t have permission to renamecmu_us_slt_cg_single_mcep_trees.cDon’t have permission to renamecmu_us_slt_cg_single_mcep_trees.hDon’t have permission to renamecmu_us_slt_cg_single_params.cDon’t have permission to renamecmu_us_slt_cg.cDon’t have permission to renamecmu_us_slt.c

A: The three reasons likely to cause this are 1. Running the install script on an distribution folder that you already ran it on once (for instance, you downloaded the OpenEars distribution and the required CMU packages, ran the script, got some errors, noticed that you had skipped a step, and then tried to just run the script a second time) in which case start over with a fresh install and try again, 2. Not cd’ing into [LOCATION_OF_DISTRIBUTION]/CMULibraries before running ./InstallOpenEars.pl, and 3. Not having downloaded all four of the required CMU packages and unarchived them in [LOCATION_OF_DISTRIBUTION]/CMULibraries before running the install script.

Although it is complaining about permissions, it isn’t necessary to run the script with sudo — if you have set everything up as described in Getting Started With OpenEars, paying attention to all steps including “Before you begin”, the install script should not require being run as superuser. [TOP]

[TOP]

Q: I am getting dozens of errors like “std::basic_string, std::allocator >::operator[](unsigned long) const”
A: You have to change the suffix of your class implementation in your app which hosts the OpenEars classes from .m to .mm so that it can support Objective-C++. So, if your class that has PocketsphinxController in it is called MyClass.m you will change it to MyClass.mm and this issue should go away. It isn’t necessary to do this for a class which hosts AudioSessionManager or OpenEarsEventsObserver only.

[TOP]

Q: There is a bug on the Simulator/recognition isn’t good on the Simulator

A: OpenEars has a new low-latency audio driver written in Audio Units which requires an Audio Session setting in order to work which isn’t supported by the Simulator. Because I know that it can be slow to debug app logic without using the Simulator, I have provided a second audio driver that is compatible with the Simulator. However, it isn’t as good as the device driver and I have spent very little time trying to debug it since I am only providing it as a nicety. With that understanding, please don’t evaluate OpenEars’ accuracy or behavior based on the Simulator, since it uses a completely different audio driver, and please don’t report Simulator-only bugs since I don’t actively support the Simulator or its driver.

[TOP]

Q: I saw a leak in OpenEars, will it prevent my app from being accepted?
A: In the current version there is a leak in a function called cst_safe_alloc that leaks 16 bytes when recognition is started. I have not been able to isolate the cause of the leak and it seems to be a very important function for Sphinxbase so I’m hesistant to get too radical about it. The leak is miniscule and would take a little less than 50 days of continuous recognition at one complete restart of the recognition loop per minute in order to leak a single MB at the given leak size. I have never heard of Apple rejecting an app that used OpenEars so this isn’t top priority but if anyone can see the fix for the leak by all means let me know.

[TOP]

Q: Does this version of OpenEars use more memory than the last version?
A: Yes, the new in-memory ringbuffer for the low-latency Audio Unit driver uses about a meg more.

[TOP]

Q: But the sample app seems to be using more memory than that extra amount when compared to the last version.
A: True, but it isn’t because the footprint of the basic OpenEars functions have increased more than the extra meg for the driver — the sample app demonstrates a number of new features which can increase OpenEars’ memory footprint if you choose to use them, such as using multiple Flite voices and changing to different language models inside a single recognition loop. The memory footprint will also spike more just in the time of speech since the speech is now processed in-memory.

[TOP]

Q: I have tried a fix for a known issue which others have been able to solve definitively, but it doesn’t work for me.
A: Many, many developers have reported situations like this that were fixed with complete re-installs of OpenEars. That suggests that not every change is always being picked up for them during new compilations for whatever reason (maybe you have different build settings in your preferences, not sure). If your system is manifesting the same symptoms of not picking up a change that others have reported as helpful to a specific issue, it shouldn’t be necessary to completely re-install OpenEars in order to experience the same benefits — just remove the app from your device and/or simulator, and then open the library and your app respectively in Xcode and select Product->Clean or type Shift-Command-k. Then you should be able to do a fresh compile and install. The initial compile will take some time, so go have a cup of tea or make a sandwich. Another issue that has similar symptoms is if you have Xcode set to automatically save when building, and you make a change to a .h file that is a search header of a project but not actually in the file navigator of the project — in order to see such changes reflected in your build, it is necessary to manually save your changes first because a linked search header doesn’t fall under the category of things Xcode will automatically save for you before doing a build.

[TOP]

Q: What license does OpenEars use?

A: There are actually five libraries used by OpenEars-enabled projects, only one of which is the OpenEars library, and you can see the license (which is very liberal) for CMU Pocketsphinx, CMU Sphinxbase, CMU Flite here and the license (which is very liberal) for MITLM here. You need to observe the terms of both of those licenses in your app as well as the OpenEars one, which shouldn’t be difficult since they are commercial-friendly licenses.

The OpenEars classes are licensed under the CDDL: http://www.opensource.org/licenses/cddl1.txt but I’m granting one exception which is that you may distribute executable-only versions of software using OpenEars files without making source code available under the terms of CDDL Version 1.0 paragraph 3.1 if source code to your software isn’t otherwise available, and without including a notice in that case inside the executable that that source code is available. This exception only applies to compiled binary freestanding apps of the sort that can be downloaded from the App Store, and not to other frameworks or systems, to which the standard CDDL applies unless otherwise agreed to by me.[TOP]

[TOP]

Q: So I can use this in commercial, closed-source apps?

A: Yes.

[TOP]

Q: Other than my following the required terms of the licenses, is there anything else I should do if I use it?

A: You must credit CMU Pocketsphinx, CMU Flite, MITLM and Politepix. A line in your “About this app” that reads something like “MyApp uses the CMU Pocketsphinx library, the CMU Flite library, MIT’s MITLM library, and Politepix’s OpenEars” would fit the bill. Links to this website are also appreciated.[TOP]

[TOP]

Q: Can I or should I reference OpenEars in my support/marketing/etc materials?
A: You are welcome to talk about OpenEars anywhere you like, as long as it doesn’t cause any confusion for your endusers about where to seek support (i.e. it must be clear that you are responsible for supporting your app) and it doesn’t imply an endorsement of your app by Politepix or any of the maintainers of the libraries that OpenEars links to.

[TOP]

Q: How can I trim down the size of the final binary for distribution?

A: You can optimize the final binary size by opening the Target Info window for your app, navigating to the Settings pane, and (for the release or distribution configuration of your app, don’t do this for debug) searching for the setting called “Deployment Postprocessing” and make sure it is checked. This should reduce the size of the included OpenEars/Pocketsphinx/Flite code in your final binary by about 8MB. If you aren’t using any Flite speech, you might be able to reduce the size more by commenting out all of the voices in OpenEarsVoiceConfig.h. If you aren’t using any speech recognition you can remove hub4wsj_sc_8k from your app. If you aren’t using any language model generation you can remove cmu07a.dic from your app. Something else that will always help a bit is to limit how far back you support other iOS versions. Search for the build setting iOS Deployment Target (OpenEarsSampleApp defaults to 3.0) and set it to something closer to the base SDK version you are supporting, for instance using a Base SDK of 4.3 and an iOS Deployment Target of 4.2.1 means that a lot of devices can run your app but the binary will have minimal bloat.[TOP]

[TOP]

Q: I thought that this version of OpenEars supported the -all_load linker flag, but I’m getting a duplicate symbol error when I use OpenEars with the flag enabled.

A: This version of OpenEars has been tested with the -all_load linker flag and it works, however, a side-effect of using this flag is that every possible class will be checked for duplicate symbols whether they are used anywhere or not. If you are getting duplicate symbol warnings with OpenEars and the -all_load linker flag, that means that another library or class that you link to (unrelated to OpenEars) uses the same method or function names as something in OpenEars or elsewhere in your app. The only thing to do here is to find the duplicated method or function name and change it in one case (and make sure that every single place it is called is also changed to reflect the new name). Although I’m willing to support the ability to compile OpenEars itself with the -all_load linker flag, I can’t support any/all issues which can come up as a result of choosing to use -all_load, and namespace issues are better supported by libraries that require that flag.

[TOP]

Q: Have any apps ever been rejected for using OpenEars?
A: I have never heard of any apps being rejected for using OpenEars, and I wouldn’t expect them to be since I’ve taken care to make sure OpenEars doesn’t do anything questionable, and where I’ve had any questions I’ve just written Apple and asked them for guidance directly. I have heard of many apps that were accepted that used OpenEars so it seems to be fine to use OpenEars. I hope that if anyone ever has an issue getting an OpenEars-enabled app accepted because of something to do with OpenEars specifically, they will fill me in.

[TOP]

Q: I still have a question, how do I get more support?
A: You can always ask for help in the forums and I’ll do my best to answer your question. Please turn on OPENEARSLOGGING and (if the issue relates to recognition) VERBOSEPOCKETSPHINX in OpenEarsConfig.h before posting an issue so we have some information to troubleshoot from. Free private email support is not given for OpenEars, but you can purchase a support incident if you would like to discuss a question via private email. Other emails regarding OpenEars (i.e. not support requests) can be sent via the contact form.

[TOP]

Q: Can I hire you to create an OpenEars-enabled app for me or adapt OpenEars?
A: Send me a note and we can discuss it if I have availability. You can now also purchase a pre-configured app project or an integration of OpenEars into one of your existing apps at the Politepix Shop.

[TOP]

Q:Did you change the title of my post/remove my post/move my post/otherwise moderate something on the forums?
A: I may have — I want the forums to stay as small and focused as possible so that the answers are right there near the front page of posts and there isn’t confusing, contradictory, outdated, overly-speculative or off-topic info in there (where on-topic == “about implementing OpenEars”), so I take out the scissors from time to time if I read something that I think is kind of a clanger or mis-titled, mis-tagged, etc. It means that it isn’t a great place for free-form conversation but it’s a good place to get a reliable answer about OpenEars implementation. I don’t think this is unusual for a troubleshooting forum, but I wanted to make it explicit since I like to know what the moderation policies are for forums that I visit.

[TOP]