Frequently Asked Questions

Do you have a question that you think would be appropriate here? Feel free to ask your question and make a suggestion to include it here on the mailing list

Adhearsion is for Ruby on Rails?

This is one of the biggest misconceptions about Adhearsion. It should be strongly stressed that Adhearsion is a Ruby framework, not a Ruby on Rails plugin or the like. Ruby on Rails, a web development framework, is probably the most popular Ruby software, but it has little to do with the Ruby language per se besides simply using it. The Ruby language is a general purpose programming language with which both Ruby on Rails and Adhearsion are written.

Adhearsion does help facilitate integration with Rails applications and it shares a few libraries with Rails, such as ActiveSupport. In Rails-integration mode, Adhearsion still exists as a completely separate process.

How can Adhearsion talk to landline or cell phones without special hardware?

This is usually so simple that it can catch people by surprise. With the proliferation of VoIP, many VoIP providers have sprung up which offer very inexpensive so-called "termination" services. Bandwidth.com and Level3 are popular examples of these. The term "termination" simply means that they operate the technologies that turn a VoIP call made up of internet packets into a phone call on the entirely separate public telephone network.

When funneling all calls through a service provider like this, it's often called "trunking" because, like the trunk of a tree, the many branches converge into one big point all the way to the ground where the roots then branch from the tree.

The following diagram should help illustrate how it works.

Diagram of telephony topology

The VoIP protocol most often used for the VoIP calling is called Session Initiation Protocol or SIP. If you're looking for services which offer this, try googling for "sip trunk" or "sip termination service" or you may find a list here.

Does Adhearsion process audio?

Adhearsion does not process the call's audio. Adhearsion is a control layer on top of a VoIP engine such as Asterisk or Voxeo PRISM. The engine handles the call, and Adhearsion provides it with instructions about how to handle the call in real-time. This is called third-party call controll (3PCC) , and this architecture is the reason Adhearsion can handle so many calls - it's delegating the heavy-lifting to a lower-level service implemented in a more performant language.

What is Asterisk?

Asterisk is an open-source telephony-engine which Adhearsion can control. Asterisk is written in C for performance and talks to Adhearsion via a socket-based protocol (AMI).

Asterisk is often fairly difficult to use for anything non-trivial and has not appropriately addressed the high barrier to entry for potential voice application developers, many coming from a web-development background. Adhearsion not only abstracts Asterisk but provides things it has never offered and likely never will offer. There is virtually nothing you can do directly in Asterisk that you can't also do from Adhearsion.

What is Voxeo PRISM (& rayo-server)?

Something is behaving strangely. Is it an Adhearsion bug?

It's very possible. The most common points of failure or peculiarities are at the SIP trunk level, the VoIP engine level, at the Adhearsion framework level and in the application (your code). You can try asking the community or the professionals for help. If it turns out to be an Adhearsion framework bug, please file a bug report More details on bug reporting may be found here.

How do I contribute my patch?

Adhearsion uses Github to manage all contributions. See the Contributing page for more information.

Why Ruby?

For several reasons:

  • Ruby strongly promotes code-reuse through first-class Object Oriented Programming.
  • Ruby code emphasizes being clean and concise.
  • Ruby has several implementations, drastically extending the code-reuse potential. The main alternative is JRuby , a stable implementation capable of running Adhearsion atop the JVM, but other implementations are available for .NET , Objective-C , as well as Ruby itself.
  • Ruby has a fantastic package manager named RubyGems which makes code reuse and distribution even easier and simpler.
  • The Ruby community is a progressive community with intelligent and pragmatic individuals with a unique culture. Things such as Agile software development and Test Driven Development are a part of the fabric of the Ruby community.
  • Adhearsion wants to attract people who get excited about learning new things.

If you've never used Ruby before, we recommend playing with the online interactive Ruby tutorial to get a feel for the language. Even if you've never programmed before, give it a try! We think you'll see what we mean by simple and clean.

What is Object Oriented Programming?

From Wikipedia:

"Object-oriented programming (OOP) is a programming paradigm that uses 'objects' and their interactions to design applications and computer programs. Programming techniques may include features such as encapsulation, modularity, polymorphism, and inheritance. It was not commonly used in mainstream software application development until the early 1990s. Many modern programming languages now support OOP."

- source and more details here

How does Adhearsion run on the JVM?

The JRuby interpreter is a full re-implementation of the Ruby programming langauge using only Java. Adhearsion strives to maintain 100% compatibility with the mainline Ruby interpreter (called Matz's Ruby Interpreter/MRI or CRuby) and JRuby.

Is Adhearsion an MVC framework?

We consider Adhearsion's Call Controller classes, its Call objects and your database models or other data source to fit the description of MVC, yes. Give it a try!

Can Adhearsion do Automatic Speech Recognition (ASR)?

Adhearsion does support the ability to call third party ASR engines. At the present time, this support is manual, but will soon be baked right in to the CallController API.

Can Adhearsion do Text to Speech (TTS)?

Adhearsion does support the ability to render TTS using an engine compatible with your VoIP engine, such as Festival (open source), Cepstral/Swift or some MRCP-compatible alternative.

Is Adhearsion slow because of Ruby?

No. The bottom line is Adhearsion will probably not be your bottleneck. Often, especially with Asterisk, it will be the telephony engine underneath Adhearsion that will be limiting your scaling. The servicing of a call with Adhearsion is almost always computationally simpler than serving even one page load with Ruby on Rails, with the main distinction that an Adhearsion call maintains a Thread and is a back-and-forth dialog, not one big textual response.

That said, if you do experience Adhearsion to be a bottleneck, you can always scale it horizontally, balancing calls between Adhearsion instances. Because Adhearsion supports message queues and database integration, dealing with shared state between Adhearsion instances is extremely easy.

How mature is the project?

Adhearsion is in use at many companies around the world. The core team have seen it scale to hundreds of simultaneous calls on a single instance. While no code is perfect, Adhearsion benefits from several years of real-world production experience.

Does Adhearsion run on Windows?

Not officially, though any Windows incompatibility is considered a bug and will therefore be fixed with due urgency. There are various technological inconsistencies when trying to make Windows behave normally vis-Ă -vis Linux / BSD / Unix. Adhearsion's core developers are all Mac OS X and Linux users, therefore Windows bugs are not found immediately.

In the meantime it is possible to use the freely available VMWare Server to install a Linux instance on Windows and use this to run Adhearsion.

Do I have to recompile Asterisk to use Adhearsion?

Not at all! Adhearsion communicates with Asterisk via a socket and the standard Asterisk APIs. You can use Adhearsion on a vanilla Asterisk v1.8+ system.

Which APIs does Adhearsion use to connect to Asterisk?

Adhearsion uses both the Application Gateway Interface (AGI) and Manager API (AMI) interfaces of Asterisk.

Adhearsion does not use vanilla AGI, but instead makes use of AsyncAGI, which is essentially AGI tunnelled over an AMI connection.

Can I try Adhearsion safely on my production Asterisk machine?

Yes! You can have a special SIP account route exclusively to Adhearsion very easily, leaving the rest of the logic perfectly intact. You can even have a single extension route to Adhearsion if you'd like. You Asterisk installation's extensions.conf only has to invoke the AGI application somewhere in it. We leave it up to you to choose where.

Is Adhearsion threadsafe?

Yes, Adhearsion is threadsafe.

Adhearsion compared to RAGI/RAMI

There are several key differences:

  • Adhearsion is a framework, not a library.
  • Adhearsion can drive VoIP engines other than Asterisk, with minimal changes to your code (sometimes none!).
  • Adhearsion is an active project with regular on-going updates. Both RAGI and RAMI are dead projects with no updates since 2005.
  • Adhearsion provides complete support for both the Asterisk AMI and AGI in one framework, whereas RAGI is for AGI and RAMI for AMI.
  • Given that complete Asterisk support is in one framework, you have the ability to develop sophisticated applications with much more ease than merging two outdated libraries.