Ade Malsasa Akbar contact
Senior author, Open Source enthusiast.
Thursday, December 20, 2018 at 14:42

Continuing the first part: Okular PDF Reader has read out loud (text to speech) feature but it needs configuration to make it works. You might find that there are very limited number of documentations available on the net about this case and if you find them you will know how complicated they are. So in this article I make it simple for you and I guarantee it's very easy to do this on Ubuntu (including Kubuntu and Neon). Ah, yeah, I include here a demonstration video you can play (don't worry it's hosted on PeerTube server, not YouTube). You will start with several basic knowledge below, then install everything needed, and then do the job. I hope this may help you to help anyone with disabilities or impairments to use GNU/Linux. Enjoy!

Subscribe to UbuntuBuzz Telegram Channel to get article updates directly.

Demo Video

This is a video screencast of me enabling Okular to read out loud a PDF document about Unix history. It's only 1 minute and is very easy. This demonstrating how to start it, run the text to speech, and close it. Hear this out!

(Video hosted on (a good PeerTube service), freely licensed, and freely downloadable)

 Basic Knowledge

You need several basic information mentioned below in order to run this TTS system on your GNU/Linux:
  • Different GNU/Linux distro may have a few different settings.
  • Like a hamburger, there are layers: your GNU/Linux system -> sound server -> dispatcher -> synthesizer -> program to open text (Okular)
  • TTS on Okular PDF Reader is basically cooperation between programs: synthesizer reads the text and translate it to speech, then dispatcher catches it,  and dispatcher sends it to sound server, finally you hear the speech.
  • Dispatcher here is a program called speech-dispatcher, must be active for TTS system to run otherwise no speech could be heard.
  • Sound server here is a program called pulseaudio, as we use Ubuntu as example (other distro may use alsa instead)
  • Synthesizer here is a program called espeak, one among many synthesizers available on GNU/Linux.
  • Short definitions: dispatcher is the connector between synthesizer and other programs; sound server is the built-in program that produce sound output on your GNU/Linux; synthesizer is the real thing that do Text To Speech (TTS). 
  • Okular needs a certain additional program ("plugin") to do TTS. It's called qtspeech5-speechd-plugin on Ubuntu. Without this, Okular will not read out loud.


  • speech-dispatcher
  • espeak
  • okular 1.4 or later (or, any version where you can see "Speak..." options under Tools menu)
  • qtspeech5-speechd-plugin (special Qt5 plugin for Okular to do TTS)
  • correct timing and configuration

Step 1 install all requirements:

Install the dispatcher:
$ sudo apt-get install speech-dispatcher 

Install the synthesizer:
$ sudo apt-get install espeak

Install the speech plugin for Okular:
$ sudo apt-get install qtspeech5-speechd-plugin

Note: in this moment the version of Qt is 5. In the future, when you still read this article, you may find the version changed and the package version or name changed as well. This article is based only on current version.

Step 2 activate the dispatcher:

Run the dispatcher first:
$ speech-dispatcher -d

Make sure dispatcher is active:
$ ps aux | grep speech-dispatcher

It's active if you see many lines of red string "speech-dispatcher" started with /usr/bin/speech-dispatcher. If you see only one red string started with grep, then it's inactive.

Step 3 do text to speech:

You must run Okular after speech-dispatcher. Otherwise, Okular cannot read out loud. If such case happens, simply restart Okular

Run Okular:
  • Run Okular from start menu. Alternatively, press Alt+F2 and type okular.

Open a PDF:
  • Drag and drop a PDF onto Okular window. Then the document appears.

Read it out loud:
  • Go to menu bar Tools > Speak Current Page. It works! You should hear the text being read out loud.

Read whole document:
  • Select Speak Whole Document to read out loud all text on all pages. It works!

Read a certain paragraph:
  • Press Ctrl+4 so your cursor turns into text selection cursor.
  • Select a paragraph.
  • Right-click > Speak Text. It works!

Stop the speech:
  • Go to menu bar Tools > Stop Speaking

Step 4 stop the dispatcher:

Run killall for speech-dispatcher:
$ killall speech-dispatcher

Once speech-dispatcher killed, Okular can no more read out loud.

Common Errors

I met some errors which are nowhere to find the easy solution on the net. Fortunately, I found the solutions and they are easy to do. I hope you can solve these problem yourselves.

Error number 1:
No text-to-speech plug-ins were found.

Explanation: this happens when you run Okular from command line and you click the speak button. This is because you don't have qtspeech5-speechd-plugin package installed. The solution is to install it. On other distro, this package may have different name.

Error number 2:
Failed to connect to speech-dispatcher.

Explanation: with Jovie (not espeak) this happens when you run any TTS but you don't have speech-dispatcher program or it's not active. The solution is to install or activate speech-dispatcher first.

Further Reading

In case you want to learn more, here's references including those from speech-dispatcher. 

Next Part...

That's all for now. I hope you can read out loud all your PDF documents now. At this moment you can only read out loud with default configuration. This means, you may find the voice is not satisfying: too fast, too harsh, etc. On the next part, I will discuss about Orca Screen Reader first, and later, I planned to write one part for configuring our TTS system (speech-dispatcher + espeak) to suit our needs including changing voice genders, languages, punctuation, speed, and more. I hope this helps everybody. Enjoy!

to be continued...

This article is licensed under CC BY-SA 3.0.