Kappa

Kappa is the Ruby library for interfacing with the Twitch.tv API.

Getting Started

gem install kappa

require 'kappa'

frag = Twitch.channels.get('lethalfrag')
puts frag.streaming?

gem 'kappa', '~> 1.0'

Configuration

When making requests to Twitch, you must specify a client ID for your application. If you do not specify a client ID, Twitch reserves the right to rate-limit your application without warning.

Your client ID can be specified through configuration, for example:

Twitch.configure do |config|
  config.client_id = 'sc2daily-v1.0.0'
end

See the Twitch.configure documentation.

Examples

Get the featured streams on the Twitch.tv homepage:

Twitch.streams.featured do |stream|
  channel = stream.channel
  puts "#{channel.display_name}: #{stream.viewer_count} viewers"
  puts "#{channel.status}"
  puts '-' * 80
end

See if certain users are streaming:

users = ['destiny', 'followgrubby', 'incontroltv']
Twitch.streams.find(:channel => users) do |stream|
  puts "#{stream.channel.name} is streaming #{stream.game_name}."
end

Get the most popular games being streamed:

Twitch.games.top(:limit => 3) do |game|
  print "#{game.name}: "
  print "#{game.viewer_count} viewers in "
  puts  "#{game.channel_count} channels"
end

Get streams for a particular game:

Twitch.streams.find(:game => 'League of Legends') do |stream|
  next if stream.viewer_count < 1000
  puts "#{stream.channel.display_name}: #{stream.viewer_count}"
end

Get info for a single user:

user = Twitch.users.get('lethalfrag')
stream = user.stream

puts user.display_name
if stream
  puts "Streaming #{stream.game_name} at #{stream.url}"
else
  puts 'Not streaming.'
end

Get the followers of a channel:

channel = Twitch.channels.get('day9tv')
channel.followers do |user|
  puts user.display_name
end

Resources

Channels

Channels serve as the home location for a user's content. Channels have a stream, can run commercials, store videos, display information and status, and have a customized page including banners and backgrounds. See the Channel documentation.

c = Twitch.channels.get('destiny')
c.nil?        # => false (channel exists)
c.stream      # => #<Kappa::V2::Stream> (current live stream)
c.url         # => "http://www.twitch.tv/destiny"
c.status      # => "Destiny - Diamond I ADC  - Number 1 Draven player..."
c.teams       # => [#<Kappa::V2::Team>]      
c.videos      # => [#<Kappa::V2::Video>, ...]
c.followers   # => [#<Kappa::V2::User>, ...]

Streams

Streams are video broadcasts that are currently live. They belong to a user and are part of a channel. See the Stream and Streams documentation.

s = Twitch.streams.get('idrajit')
s.nil?          # => false (currently live)
s.game_name     # => "StarCraft II: Heart of the Swarm"
s.viewer_count  # => 7267
s.channel.url   # => "http://www.twitch.tv/idrajit"

Users

These are members of the Twitch community who have a Twitch account. If broadcasting, they can own a stream that they can broadcast on their channel. If mainly viewing, they might follow or subscribe to channels. See the User documentation.

u = Twitch.users.get('snoopeh')
u.nil?                    # => false (user exists)
u.channel                 # => #<Kappa::V2::Channel>
u.following.map(&:name)   # => ["national_esl1", "dreamhacklol", "riotgames"]

Videos

Videos are broadcasts or highlights owned by a channel. Broadcasts are unedited videos that are saved after a streaming session. Highlights are videos edited from broadcasts by the channel's owner. See the Video and Videos documentation.

v = Twitch.videos.get('a395995729')
v.nil?          # => false (video exists)
v.title         # => "DreamHack Open Stockholm 26-27 April"
v.game_name     # => "StarCraft II: Heart of the Swarm"
v.recorded_at   # => 2013-04-26 18:33:48 UTC
v.view_count    # => 12506

Teams

Teams are an organization of channels. See the Team documentation.

t = Twitch.teams.get('teamliquid')
t.nil?          # => false (team exists)
t.display_name  # => "TeamLiquid"
t.info          # => "TeamLiquid is awesome. and esports. video games. \n\n"
t.updated_at    # => 2013-05-24 00:17:10 UTC

Games

Games are categories (e.g. League of Legends, Diablo 3) used by streams and channels. Games can be searched for by query. See the Game, Games, and GameSuggestion documentation.

top = Twitch.games.top(:limit => 2)
top.map(&:name)  # => ["League of Legends", "StarCraft II: Heart of the Swarm"]

g = Twitch.games.top(:limit => 1).first
g.name                   # => "League of Legends"
g.channel_count          # => 906
g.viewer_count           # => 79223
g.box_images.medium_url  # =>"http://static-cdn.jtvnw.net/ttv-boxart/31412.jpg"

s = Twitch.games.find(:name => 'diablo', :live => true)
s.map(&:name)        # => ["Diablo III", "Diablo II", "Diablo"]
s.map(&:popularity)  # => [120, 4, 1]

Errors

All errors derive from Twitch::Error.

• Twitch:Error - Base class for all errors.
• Twitch::Error::ResponseError - Base class for all Twitch.tv API response errors.
• Twitch::Error::FormatError - The returned data was incorrectly formatted (e.g. invalid JSON).
• Twitch::Error::ClientError - The server returned a 4xx status code.
• Twitch::Error::ServerError - The server returned a 5xx status code.

All ResponseError errors have additional diagnostic information:

e.status # => 422
e.body   # => '{"status":422,"message":"...","error":"..."}'
e.url    # => "https://api.twitch.tv/streams/desrow"

See the ResponseError documentation.

Documentation

• Current release: http://rdoc.info/gems/kappa/frames
• Latest master: http://rdoc.info/github/schmich/kappa/frames
• Twitch REST API: https://github.com/justintv/Twitch-API

Versioning

Library version

Kappa adheres to the Semantic Versioning 2.0.0 specification. Most importantly, any compatibility- or API-breaking changes will result in a new major version (e.g. 1.x.x to 2.x.x). Because of this, you should use a pessimistic version constraint when taking a dependency on this library. For example:

gem 'kappa', '~> 1.0'

Any new backwards-compatible features will result in a new minor version (e.g. x.1.x to x.2.x) while any backwards-compatible bugfixes will result in a new patch version (e.g. x.x.1 to x.x.2).

Twitch API versions

Twitch supports multiple versions of their API simultaneously, with each version potentially providing different data and behaving differently. Because of this, you can specify which version of the Twitch API you wish to use. This is done through Kappa configuration.

For example, if you want to use the V2 Twitch API:

Twitch.configure do |config|
  config.client_id = 'sc2daily-v1.0.0'
  config.api = Twitch::V2
end

Twitch::V2 is the default and is currently the only supported API version.

Contributing

• Fork and clone the repo.
• Create a branch for your changes.
• Run bundle install to install development requirements.
• Implement your feature or bug fix.
• Add specs under the spec folder to prevent regressions or to test new code.
• Add YARD documentation for new features. Run rake yard to view documentation.
• Run rake coverage to run specs with code coverage. All specs must pass; coverage must remain at 100%. Run rake coverage:view to see a detailed report.
• Commit and push your changes.
• Submit a pull request.

License

Copyright © 2013 Chris Schmich
MIT License. See LICENSE for details.