btgpt Beta Resources
Welcome to btgpt beta
Page Status: I am in the process of significant changes and rewrites to these instructions in readiness for BTSpeak Beta test group access.
Thank you for your interest in testing the btg beta on your BTSpeak! I hope you will find the software functional and enjoyable to use.
I invite your feedback on any aspect of the experience, from communications and documentation, through to configuring and using btg.
I have intentionally provided extensive detail and technical explanations for each step required to configure and use the btg package. Some users will have prior Linux and shell experience; for others this might be their first time in a Linux shell.
If you would like to learn more about the bash Shell and unix/Linux commands, I highly recommend a fantastic podcast called Taming the Terminal. Though it makes references to terminal on the Mac, it largely can be applied to bash on the BTSpeak.
btg – Beta 2 released on 2024.04.29
Ok, let’s get right to it!
Do you have your Open AI key generated and correctly placed on your BTSpeak?
The key should be around 50 characters in length and commence with sk-
It should be located in either
/home/pi/.openAI_key
or
/home/pi/.openAPI_key
When you run btg, it will check for the key and generate a relevant error if it is not found.
Preparing this file on a computer, and saving it to the BTSpeak public folder through file sharing, is probably the main way to install this key file. You can then move and rename it using the BTSpeak File Browser.
Note About Free or Funded Keys
If you have just generated your free Open AI key for the first time, it may not be immediately usable, even though it is named and saved correctly. It may automatically start working at a later point. I suspect that when Open AI is under extreme loads, it stops access to free keys until the load reduces. These instructions will be updated if we gain more information about this issue – which is not a bug in the btg app, but an Open AI response containing ann error something like
“Your request to Open AI API failed: insufficient_quota. You exceeded your current quota, please check your plan and billing details. …”
We know that users who generate a new key and then fund their account, do get proper access.
Note, Chat GPT is supposed to work on the free tier, but one beta user encountered the problem I described above.
That said, I strongly encourage you to consider funding your Open AI account., either immediately, or after you spend some time with Chat GPT. It is an incredibly affordable way to access the latest versions of Open AI’s services like Chat GPT, and is pay as you go. No monthly subscription, like Chat GPT Plus!
You need to fund a minimum of five dollars to your account in order to access the latest models. A sound approach is to fund $10 and top-up when you are down to $5 remaining. This lets you know your usage, but quite affordably.
The accuracy, intelligence and usefulness of GPT 4 and GPT 4 turbo over the free GPT 3.5 models is quite extraordinary.
the full directory path for the btg directory will be /home/pi/BTSpeak/btg
7: Check the files listed in the directory.
ls -1
8: The readme.txt file in the zip file gives further testing and installation instructions. If you want to read ahead here, The contents of the readme is included below at the next heading level 1.
What Files Are Included in the btg folder?
- btgpt.conf – the default configuration file that needs to be placed in the home directory. It allows you to adjust speech settings and other chat gpt settings.
- readme.txt – further instructions on configuring and using btgpt, .
- get-openai-key.txt – a lightly edited version of the BTSpeak help file detailing how to get an Open AI key;
Contents of btg-beta2.zip readme.txt file
Readme V2.0
Intro
Thank you for participating in the btg beta.
Testing btg
5: Run btg residing in the /BTSpeak/bin directory
You should either get a welcome message and beta version number or a spoken warning about problems with finding, or the format of, your OpenAI key.
If you get a start-up error about your key, you need to double-check it is in the right place, with the right name (note the upper case letters AI or API) and that it is in the right format. It should probably start with sk-
Also check beta resources webpage notes about recently generated free vs funded keys.
### Assuming btg Starts and Welcomes You:
6: Type a question (termed prompt) and press enter. Wait a few seconds and (if all is well) you will hear your answer being read out to you.
7: Pressing enter on a blank line will immediately stop ongoing speech, including stopping the welcome message voice immediately after starting btg.
8: to leave the btg app, Type q and enter.
Testing ask
9: Test ask in the /bTSpeak/bin directory
Ask allows you to ask a single question of Chat GPT.
Lets Start with the usage message for ask by providing no arguments. This message is sent to the screen, not self voiced. Use Review to read it.
ask
Try using ask to get a question answered.
ask What is the meaning of life?
ask who is Deane Blazie?
Avoid questions with apostrophes for now.
If all is well, you should hear a GPT response to your question.
10: Now we have ensured that btg and ask can be run, we can fully install and configure gpt and ask for your needs.
Installing the Configuration File
Note, btg will run fine without the configuration file, but you won’t be able to adjust any of the speech settings or other default aspects of the software. I strongly recommend employing the configuration file.
11: Copy the btgpt configuration file to its correct location
Assuming you are in the
/home/pi/BTSpeak/btg
directory
cp btgpt.conf /home/pi/.btgpt.conf
This installs the configuration file in your home directory as a hidden file. You can edit it with the BTSpeak editor, see below.
Adding btg to your User Menu
You may wish to have btg readily available from the BTSpeak User menu. This means you don’t need to enter the shell in order to run the app.
To do this we need to add a line to the user menu file.
14: in the file browser find the BTSpeak folder in your home directory and press enter to move into the directory.
15: find the user.menu file and press enter to open it in the editor.
16: add the following line to the end of the file:
btgpt: execute /home/pi/btg/btg
Note: this line will include btgpt as one of the options in your user menu – accessed by o-chord u. Its default shortcut letter will be b.
If you wish to use b as the shortcut for another user command, you can change the default letter as follows:
c=btgpt: execute /home/pi/btg/btg
This will change the btgpt shortcut to c instead of b.
save and exit the file and the user shortcut should be ready to go.
Note, it is not meaningful to add ask to the user menu or the applications menu, as ask only works when given a meaningful argument (i.e. your question).
Using ask from within the BTSpeak editor
Now that ask is in the path, you are able to use it from within the editor.
Note, You can only do this from within an editable file (not the welcome screen, which is write-protected.).
press control-t either by x-chord t or by pressing t-7-8 chord
then type ask
Basic ask example:
ask who invented Linux?
Quoted example:
ask “what is the Braille ‘n Speak”
Note: the simple form of ask usage must not include the apostrophe character in your question. The apostrophe is a special quoting character in the shell. If in doubt, place your question in double quotes.
If all goes well, you should hear the answer to your question, a short pause and then ‘new file is open’
You are move to the new file and it will contain the text of Chat GPT’s answer to your question. If its answer was more than one paragraph in length, all the answer is placed in the file, but only the first paragraph is spoken aloud.
You can either close and exit this file, save it, or copy part or all of its contents, to use in another file.
To close and exit the file, press control-x followed by the letter n
You will be returned to your starting file.
Note: for complex reasons around speech output processing, you may notice that after using the ask command it waits for a couple of seconds before returning. This is because I have done a heuristically calculated guess of how long it will take the speech to speak the answer. If we can improve on this down the track, we will.
Explaining and Editing the .btgpt.conf File
Note when in the file browser, you will need to show hidden files by pressing h, in order to see this file and open it in the editor.
When you use the BTSpeak editor (or another editor) to edit the .btgpt.conf file, you will find explanatory comment lines starting with the hash symbol.
Then, you will find a variety of Key=Value pairs, similar but different from a Windows .ini file.
As a general rule, you should not use quotes ” to surround your values to the right of the = equals sign.
You should not use spaces on either side of the = equals sign.
example line
dtVoiceName=p
I have specially coded the app to ignore the capitalisation of the key names in the config file, but they are generally in camelCase for the technically curious.
I have also added checks for data consistency and known value ranges where I can, but you should only edit what you need in the file. If something is unclear, it’s best to leave it blank or at defaults.
If you get odd behaviour you can retrieve the original btgpt.conf file from the btg folder, or you can place a # hash sign at the start of any line to work out if it is the problem.
Note that on screen, if keys are found that are not recognised, they will be noted. However, The app should still operate properly.
Default Speech Settings
Whether the .btgpt.conf file is present or not, system defaults are built into the app. Many of the settings in the configuration file are left blank, or are identical to what is in the app itself. You can edit or enter values as needed.
Configuration File Speech Settings
In this first release of BTG, the app speaks directly to the DECtalk via the say command. For this reason, it has its own voice settings separate from your BTSpeak speech settings set via s-chord.
The current btg defaults for the DECtalk are as follows:
- dtVoiceName=P – for Paul. The first letter of each name is sufficient in the config file.
- dtRate=280 – words per minute.
- dtVolume=60 – percent
- dtPitch=100 – this is the average pitch in Hz. It is about equivalent to pitch minus 2 for Paul in BTSpeak speech settings.
I set the pitch this way because many BTSpeak users have found that DECtalk sounds clearer and less harsh at this lower pitch, especially through the device’s inbuilt speakers.
Extra Speech Settings
Because BTG is designed to interpret markdown output, I have implemented voice fonts to represent different types of output. So, the default voice fonts are set as follows:
- Bold is 15 percent louder than regular text.
- Italics and text in single quotes or back ticks are 15 points higher in pitch than regular text.
- H1 and H2 are using the contrast voice (Harry by default) and speaking 25 words per minute slower.
- Block quotes use the contrast voice (Harry).
Some (but not all) of These voice font aspects are adjustable and can be tailored using the following four additional speech settings:
- dtOffsetRate=-25 – All the offsets can be a positive or negative number. It is set to -25 (minus 25) by default, thus slowing down headings by 25 words per minute.
- dtOffsetVolume=15 –
- dtOffsetPitch=15
- dtContrastVoice=h – it is set to Harry.
Technical explanation: Because each voice has its own default pitch, when you adjust the pitch, it needs to be associated with that voice, using the DECtalk Design Voice feature. The Design voice name is Val or v. Voice V for Val has been set to a combination of your preferred voice and your preferred pitch. This means you can set your contrast voice to V – for Val, and it will be the same as your standard voice and pitch combination. It also means that if your primary voice is Paul, but at a lower pitch, you can set the contrast voice to P – for Paul, and it will be at Paul’s default pitch.
I appreciate that The last few paragraphs might be a bit overwhelming, or unclear before you have used btg, but I am providing the information for reference. To start out, I recommend Just using the defaults for these last four offset settings; you can experiment once you are more familiar with how the app works, and how you find the markdown interpritation.
Other configuration file settings.
Take a read through the rest of the configuration file, but only make changes if you are pretty sure of what you are doing.
- For example, if you have a paid Open AI key you will likely want to change the model to something like gpt-4-turbo-preview
- You might want to change the system prompts sent to gpt, but I recommend starting with the defaults I have set up to see how things work. Once you understand the configuration file you could add your name to the GPT prompt and tell it where in the world you are, your preferred language and whether you want metric. You could ask it to use tactile and auditory metaphores in its descriptions and explanations.
- You might wish to keep a history of your Chat GPT conversations. set this value to y if you want your history saved.
ENABLE_HISTORY=y
btgpt and Espeak or using Speech Dispatcher
As previously mentioned, there is strong interest in a version of btg that isn’t reliant on the DECtalk. I am exploring a couple of different approaches to this need, but they may impact the voice font facility. If you like the voice font concept and believe it adds value to the app, please let me know that too.
I am also exploring ways to more effectively allow review of btg output and messages, so stay tuned.
Bugs, Feedback, and Suggestions
Please let me know how you find btg and ask. You can contact me by email at
tim@timnoonan.com.au
Remember, at present, this is not a Blazie Technologies application. For that reason, please if you are testing the beta and not part of Blazie’s beta group, don’t clutter the BTSpeak list with btg problems or troubleshooting. Also, don’t email or call Blazie tech support about btg issues.
Of course, when the app goes live, if you find btg useful and want to share your findings or tips with the BTSpeak community, please go ahead and post about your btg experiences.
This is only btg beta 1; I have a lot of ideas to explore and features I think would be of value. It’s taken a lot of work to get btg to this point, but I think it is now pretty solid and that the code is in reasonably good shape for creative experiments and expansions down the track.
Please let me know how you find it and what things you might like me to consider for future versions.
Enjoy
Tim Noonan tim@timnoonan.com.au
Tweetwebsite by twpg