Bixby Developer Center

Bixby's development environment includes a set of library capsules that you can import to provide extended functionality. Using Bixby's libraries lets your capsule handle complex data types, understand more complicated natural language references, and access device features. Library capsules give you the ability to:

• Handle dates, times, and date intervals, including training to handle natural language utterances such as "next Tuesday", "January 23rd at 5pm", and "the week after Christmas"
• Understand locations, including specifying addresses, cities, points of interest, and geographic regions
• Access the user's contacts
• Make phone calls and send text messages on supported devices

And much more. Library capsules always provide new concepts for use in your capsules; depending on their functionality, they might also provide actions, dialog, and training.

Using Capsules

To use a library capsule, it must be imported. In your capsule.bxb file, include an import statement in the capsule-imports block:

capsule {
  capsule-imports {
    import (viv.time) {
      as (time) version (2.58.56)
    }
  }
}

This import lets you refer to concepts and actions in the viv.time.* namespace simply with time.*.

Capsules import their own dependencies; your capsule does not need to import these separately.

Extending Library Capsule Concepts

Many concepts in library capsules can be used directly by your capsules, but some are designed to be extended or given roles by your capsule. Consult the specific library capsule documentation for guidance. You can always extend library capsule concepts to provide extra functionality relevant to your capsule.

Overriding with Match Patterns

When capsules provide dialog, you might want to override their prompts to be more specific for your capsule's use case. In order to do this, you'll need to provide a match pattern that matches the library capsule'a dialog but contains at least one model (concept or action) unique to your capsule. That way, your match pattern is more specific than the match patterns contained in the library, and will be chosen as the "best" match pattern for that use case when Bixby's planner dynamically generates its programs.

For example, if you're trying to override dialog for an address prompt coming from viv.self, you might try:

dialog (Elicitation) {
  match: viv.self.Address (address) {
    to-input: viv.self.GetProfile {
      to-output: viv.self.Profile {
        to-input: BookRoom (book)
      }
    }
  }
  template ("What is your address?")
}

Most of the concepts in this match pattern come from viv.self, but the last concept referred to, BookRoom, is specific to the capsule importing the library, making this match pattern more specific than any pattern imported from viv.self.

If you're having trouble overriding library dialog, the debug console in Bixby Developer Studio can help. Try a query that produces the dialog you're trying to override and examine the planner output to see what models you'll need to specify in your match pattern.

Library Capsule Versions

Last updated December 1, 2020

When importing library capsules, these are the current versions to specify:

Importing Capsule Versions

Instead of indicating a version for each imported capsule, once you import a library, you should use version-from to transitively import any of its dependencies. This is useful in order to keep versions aligned and prevent your capsule dependency chain from using two different versions of the same imported capsule.

Because of the transitive nature of version-from, you only have to point to a capsule that indirectly imports that capsule.

Take, for example, the following diagram, that shows various capsule dependencies for each of the library capsules shown above:

The dotted lines in the diagram indicate possible transitive imports. Note that the following library capsules can import or be imported by other internal library capsules:

• bixby.textMessage
• bixby.phoneCall
• viv.shareVia
• viv.money

In the example below, the capsule first specifies the version when importing viv.location. It then uses location to get capsule versions for other imported capsules.

  capsule-imports {
    import (viv.location) { as (location) version (1.0.48)}
    import (viv.geo) { as (geo) version-from (location)}
    import (viv.self) { as (self) version-from (location) }
    import (bixby.contact) {as (contact) version-from (location)}
  }

View on GitHub

Capsules

These are some of the most commonly used library capsules along with links to further discussion.

• Audio Player (bixby.audioPlayer)
  Describes how to use the AudioPlayer library to play audio streams within Bixby, without relying on external player applications.

• Contact (bixby.contact)
  Describes how to search for and save contact information.

• Core (viv.core)
  A low-level capsule that defines concepts used by other library capsules.

• DateTime (viv.time)
  Describes how to work with a variety of relative and absolute date/time expressions.

• Entity (viv.entity) (Deprecated)
  Provider helper models, layout macros, and dialogs for presenting certain kinds of data sets.

• Geography (viv.geo)
  Describes how to work with geospatial concepts and localities.

• Image (viv.image) (Deprecated)
  Describes how to work with concepts representing image metadata.

• Location (viv.location)
  Describes how to use the location/contact-based autosuggest library.

• Measurement (viv.measurement)
  Describes how to work with concepts representing units of measurement, including conversion between compatible units.

• Money (viv.money)
  Describes how to work with currency.

• Navigation (viv.navigation)
  Describes how to provide navigation to a selected destination with Google Maps.

• Open Hours (viv.openHours)
  Describes a set of concepts representing open hours for businesses.

• Phone Call (bixby.phoneCall)
  Provides a way for capsules to place phone calls.

• Profile (viv.self)
  Describes how to access and update user profile information.

• Rating (viv.rating)
  Describes how to work with concepts representing ratings and reviews.

• Sharing (viv.sharevia)
  Describes how to send content to other applications or capsules.

• Text Message (bixby.textMessage)
  Provides a way for capsules to send SMS text messages.