Mercurial > public > pelican-blog

annotate content/Coding/011-ts3-python-javascript.rst @ 5:4b5cdcc351c5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use a cloned copy of pelican-bootstrap3 repo as my theme.
author Brian Neal <bgneal@gmail.com>
date Fri, 31 Jan 2014 19:12:50 -0600
parents 7ce6393e6d30
children 49bebfa6f9d3
rev   line source
bgneal@4 1 A TeamSpeak 3 viewer with Python & Javascript
bgneal@4 2 #############################################
bgneal@4 3
bgneal@4 4 :date: 2012-01-20 19:15
bgneal@4 5 :tags: Python, Javascript, TeamSpeak
bgneal@4 6 :slug: a-teamspeak-3-viewer-with-python-javascript
bgneal@4 7 :author: Brian Neal
bgneal@4 8
bgneal@4 9 The Problem
bgneal@4 10 ===========
bgneal@4 11
bgneal@4 12 My gaming clan started using `TeamSpeak 3`_ (TS3) for voice communications, so
bgneal@4 13 it wasn't long before we wanted to see who was on the TS3 server from the clan's
bgneal@4 14 server status page. Long ago, before I met Python, I had built the clan a server
bgneal@4 15 status page in PHP. This consisted of cobbling together various home-made and
bgneal@4 16 3rd party PHP scripts for querying game servers (Call of Duty, Battlefield) and
bgneal@4 17 voice servers (TeamSpeak 2 and Mumble). But TeamSpeak 3 was a new one for us,
bgneal@4 18 and I didn't have anything to query that. My interests in PHP are long behind
bgneal@4 19 me, but we needed to add a TS3 viewer to the PHP page. The gaming clan's web
bgneal@4 20 hosting is pretty vanilla; in other words PHP is the first class citizen. If I
bgneal@4 21 really wanted to host a Python app I probably could have resorted to Fast CGI or
bgneal@4 22 something. But I had no experience in that and no desire to go that way.
bgneal@4 23
bgneal@4 24 I briefly thought about finding a 3rd party PHP library to query a TS3 server.
bgneal@4 25 The libraries are out there, but they are as you might expect: overly
bgneal@4 26 complicated and/or pretty amateurish (no public source code repository). I even
bgneal@4 27 considered writing my own PHP code to do the job, so I started looking for any
bgneal@4 28 documentation on the TS3 server query protocol. Luckily, there is a `TS3
bgneal@4 29 query protocol document`_, and it is fairly decent.
bgneal@4 30
bgneal@4 31 But, I just could not bring myself to write PHP again. On top of this, the
bgneal@4 32 gaming clan's shared hosting blocks non-standard ports. If I did have a PHP
bgneal@4 33 solution, the outgoing query to the TS3 server would have been blocked by the
bgneal@4 34 host's firewall. It is a hassle to contact their technical support and try to
bgneal@4 35 find a person who knows what a port is and get it unblocked (we've had to do
bgneal@4 36 this over and over as each game comes out). Thus it ultimately boiled down to me
bgneal@4 37 wanting to do this in Python. For me, life is too short to write PHP scripts.
bgneal@4 38
bgneal@4 39 I started thinking about writing a query application in Python using my
bgneal@4 40 dedicated server that I use to host a few Django_ powered websites. At first I
bgneal@4 41 thought I'd generate the server status HTML on my server and display it in an
bgneal@4 42 ``<iframe>`` on the gaming clan's server. But then it hit me that all I really
bgneal@4 43 needed to do is have my Django_ application output a representation of the TS3
bgneal@4 44 server status in JSON_, and then perhaps I could find a slick jQuery_ tree menu
bgneal@4 45 to display the status graphically. I really liked this idea, so here is a post
bgneal@4 46 about the twists and turns I took implementing it.
bgneal@4 47
bgneal@4 48 The Javascript
bgneal@4 49 ==============
bgneal@4 50
bgneal@4 51 My searching turned up several jQuery tree menu plugins, but in the end I
bgneal@4 52 settled on dynatree_. Dynatree had clear documentation I could understand, it
bgneal@4 53 seems to be actively maintained, and it can generate a menu from JSON. After one
bgneal@4 54 evening of reading the docs, I built a static test HTML page that could display
bgneal@4 55 a tree menu built from JSON. Here the Javascript code I put in the test page's
bgneal@4 56 ``<head>`` section:
bgneal@4 57
bgneal@4 58 .. sourcecode:: javascript
bgneal@4 59
bgneal@4 60 var ts3_data = [
bgneal@4 61 {title: "Phantom Aces", isFolder: true, expand: true,
bgneal@4 62 children: [
bgneal@4 63 {title: "MW3", isFolder: true, expand: true,
bgneal@4 64 children: [
bgneal@4 65 {title: "Hogan", icon: "client.png"},
bgneal@4 66 {title: "Fritz!!", icon: "client.png"}
bgneal@4 67 ]
bgneal@4 68 },
bgneal@4 69 {title: "COD4", isFolder: true, expand: true,
bgneal@4 70 children: [
bgneal@4 71 {title: "Klink", icon: "client.png"}
bgneal@4 72 ]
bgneal@4 73 },
bgneal@4 74 {title: "Away", isFolder: true, children: [], expand: true}
bgneal@4 75 ]
bgneal@4 76 }
bgneal@4 77 ];
bgneal@4 78
bgneal@4 79 $(function(){
bgneal@4 80 $("#ts3-tree").dynatree({
bgneal@4 81 persist: false,
bgneal@4 82 children: ts3_data
bgneal@4 83 });
bgneal@4 84 });
bgneal@4 85
bgneal@4 86 Note that ``client.png`` is a small icon I found that I use in place of
bgneal@4 87 dynatree's default file icon to represent TS3 clients. If I omitted the icon
bgneal@4 88 attribute, the TS3 client would have appeared as a small file icon. Channels
bgneal@4 89 appear as folder icons, and this didn't seem to unreasonable to me. In other
bgneal@4 90 words I had no idea what a channel icon would look like. A folder was fine.
bgneal@4 91
bgneal@4 92 With dynatree, you don't need a lot of HTML markup, it does all the heavy
bgneal@4 93 lifting. You simply have to give it an empty ``<div>`` tag it can render
bgneal@4 94 into.
bgneal@4 95
bgneal@4 96 .. sourcecode:: html
bgneal@4 97
bgneal@4 98 <body>
bgneal@4 99 <div id="ts3-tree"></div>
bgneal@4 100 </body>
bgneal@4 101 </html>
bgneal@4 102
bgneal@4 103 Here is a screenshot of the static test page in action.
bgneal@4 104
bgneal@4 105 .. image:: /images/011-tree1.png
bgneal@4 106
bgneal@4 107 Nice! Thanks dynatree! Now all I need to do is figure out how to dynamically
bgneal@4 108 generate the JSON data and get it into the gaming clan's server status page.
bgneal@4 109
bgneal@4 110 The Python
bgneal@4 111 ==========
bgneal@4 112
bgneal@4 113 Looking through the `TS3 protocol documentation`_ I was somewhat surprised to
bgneal@4 114 see that TS3 used the Telnet protocol for queries. So from my trusty shell I
bgneal@4 115 telnet'ed into the TS3 server and played with the available commands. I made
bgneal@4 116 notes on what commands I needed to issue to build my status display.
bgneal@4 117
bgneal@4 118 My experiments worked, and I could see a path forward, but there were still some
bgneal@4 119 kinks to be worked out with the TS3 protocol. The data it sent back was escaped
bgneal@4 120 in a strange way for one thing. I would have to post-process the data in Python
bgneal@4 121 before I could use it. I didn't want to reinvent the wheel, so I did a quick
bgneal@4 122 search for Python libraries for working with TS3. I found a few, but quickly
bgneal@4 123 settled on Andrew William's python-ts3_ library. It was small, easy to
bgneal@4 124 understand, had tests, and a GitHub page. Perfect.
bgneal@4 125
bgneal@4 126 One of the great things about Python, of course, is the interactive shell. Armed
bgneal@4 127 with the `TS3 protocol documentation`_, python-ts3_, and the Python shell, I was
bgneal@4 128 able to interactively connect to the TS3 server and poke around again. This time
bgneal@4 129 I was sitting above telnet using python-ts3_ and I confirmed it would do the job
bgneal@4 130 for me.
bgneal@4 131
bgneal@4 132 Another evening was spent coding up a Django view to query the TS3 server using
bgneal@4 133 python-ts3_ and to output the channel status as JSON.
bgneal@4 134
bgneal@4 135 .. sourcecode:: python
bgneal@4 136
bgneal@4 137 from django.conf import settings
bgneal@4 138 from django.core.cache import cache
bgneal@4 139 from django.http import HttpResponse, HttpResponseServerError
bgneal@4 140 from django.utils import simplejson
bgneal@4 141 import ts3
bgneal@4 142
bgneal@4 143 CACHE_KEY = 'ts3-json'
bgneal@4 144 CACHE_TIMEOUT = 2 * 60
bgneal@4 145
bgneal@4 146 def ts3_query(request):
bgneal@4 147 """
bgneal@4 148 Query the TeamSpeak3 server for status, and output a JSON
bgneal@4 149 representation.
bgneal@4 150
bgneal@4 151 The JSON we return is targeted towards the jQuery plugin Dynatree
bgneal@4 152 http://code.google.com/p/dynatree/
bgneal@4 153
bgneal@4 154 """
bgneal@4 155 # Do we have the result cached?
bgneal@4 156 result = cache.get(CACHE_KEY)
bgneal@4 157 if result:
bgneal@4 158 return HttpResponse(result, content_type='application/json')
bgneal@4 159
bgneal@4 160 # Cache miss, go query the remote server
bgneal@4 161
bgneal@4 162 try:
bgneal@4 163 svr = ts3.TS3Server(settings.TS3_IP, settings.TS3_PORT,
bgneal@4 164 settings.TS3_VID)
bgneal@4 165 except ts3.ConnectionError:
bgneal@4 166 return HttpResponseServerError()
bgneal@4 167
bgneal@4 168 response = svr.send_command('serverinfo')
bgneal@4 169 if response.response['msg'] != 'ok':
bgneal@4 170 return HttpResponseServerError()
bgneal@4 171 svr_info = response.data[0]
bgneal@4 172
bgneal@4 173 response = svr.send_command('channellist')
bgneal@4 174 if response.response['msg'] != 'ok':
bgneal@4 175 return HttpResponseServerError()
bgneal@4 176 channel_list = response.data
bgneal@4 177
bgneal@4 178 response = svr.send_command('clientlist')
bgneal@4 179 if response.response['msg'] != 'ok':
bgneal@4 180 return HttpResponseServerError()
bgneal@4 181 client_list = response.data
bgneal@4 182
bgneal@4 183 # Start building the channel / client tree.
bgneal@4 184 # We save tree nodes in a dictionary, keyed by their id so we can find
bgneal@4 185 # them later in order to support arbitrary channel hierarchies.
bgneal@4 186 channels = {}
bgneal@4 187
bgneal@4 188 # Build the root, or channel 0
bgneal@4 189 channels[0] = {
bgneal@4 190 'title': svr_info['virtualserver_name'],
bgneal@4 191 'isFolder': True,
bgneal@4 192 'expand': True,
bgneal@4 193 'children': []
bgneal@4 194 }
bgneal@4 195
bgneal@4 196 # Add the channels to our tree
bgneal@4 197
bgneal@4 198 for channel in channel_list:
bgneal@4 199 node = {
bgneal@4 200 'title': channel['channel_name'],
bgneal@4 201 'isFolder': True,
bgneal@4 202 'expand': True,
bgneal@4 203 'children': []
bgneal@4 204 }
bgneal@4 205 parent = channels[int(channel['pid'])]
bgneal@4 206 parent['children'].append(node)
bgneal@4 207 channels[int(channel['cid'])] = node
bgneal@4 208
bgneal@4 209 # Add the clients to the tree
bgneal@4 210
bgneal@4 211 for client in client_list:
bgneal@4 212 if client['client_type'] == '0':
bgneal@4 213 node = {
bgneal@4 214 'title': client['client_nickname'],
bgneal@4 215 'icon': 'client.png'
bgneal@4 216 }
bgneal@4 217 channel = channels[int(client['cid'])]
bgneal@4 218 channel['children'].append(node)
bgneal@4 219
bgneal@4 220 tree = [channels[0]]
bgneal@4 221
bgneal@4 222 # convert to JSON
bgneal@4 223 json = simplejson.dumps(tree)
bgneal@4 224
bgneal@4 225 cache.set(CACHE_KEY, json, CACHE_TIMEOUT)
bgneal@4 226
bgneal@4 227 return HttpResponse(json, content_type='application/json')
bgneal@4 228
bgneal@4 229 I have to make three queries to the TS3 server to get all the information I
bgneal@4 230 need. The ``serverinfo`` command is issued to retrieve the TS3 virtual server's
bgneal@4 231 name. The ``channellist`` command retrieves the list of channels. The
bgneal@4 232 ``clientlist`` command gets the list of TS3 clients that are currently
bgneal@4 233 connected. For more information on these three commands see the TS3 query
bgneal@4 234 protocol document.
bgneal@4 235
bgneal@4 236 The only real tricky part of this code was figuring out how to represent an
bgneal@4 237 arbitrary, deeply-nested channel tree in Python. I ended up guessing that
bgneal@4 238 ``cid`` meant channel ID and ``pid`` meant parent ID in the TS3 query data. I
bgneal@4 239 squirrel away the channels in a ``channels`` dictionary, keyed by channel ID.
bgneal@4 240 The root channel has an ID of 0. While iterating over the channel list, I can
bgneal@4 241 retrieve the parent channel from the ``channels`` dictionary by ID and append
bgneal@4 242 the new channel to the parent's ``children`` list. Clients are handled the same
bgneal@4 243 way, but have different attributes. By inspecting the ``clientlist`` data in the
bgneal@4 244 Python shell, I noticed that my Telnet client also showed up in that list.
bgneal@4 245 However it had a ``client_type`` of 1, whereas the normal PC clients had a
bgneal@4 246 ``client_type`` of 0.
bgneal@4 247
bgneal@4 248 I decided to cache the results for 2 minutes to reduce hits on the TS3 server,
bgneal@4 249 as it has flood protection. This probably isn't needed given the size of our
bgneal@4 250 gaming clan, but Django makes it easy to do, so why not?
bgneal@4 251
bgneal@4 252 Putting it all together
bgneal@4 253 =======================
bgneal@4 254
bgneal@4 255 At this point I knew how to use my Django application to query the TS3 server
bgneal@4 256 and build status in JSON format. I also knew what the Javascript and HTML on the
bgneal@4 257 gaming clan's server status page (written in PHP) had to look like to render
bgneal@4 258 that JSON status.
bgneal@4 259
bgneal@4 260 The problem was the server status page was on one server, and my Django
bgneal@4 261 application was on another. At first I thought it would be no problem for the
bgneal@4 262 Javascript to do a ``GET`` on my Django server and retrieve the JSON. However I
bgneal@4 263 had some vague memory of the browser security model, and after some googling I
bgneal@4 264 was reminded of the `same origin policy`_. Rats. That wasn't going to work.
bgneal@4 265
bgneal@4 266 I briefly researched JSONP_, which is the technique that Facebook & Google use
bgneal@4 267 to embed those little "like" and "+1" buttons on your web pages. But in the end
bgneal@4 268 it was just as easy to have the PHP script make the ``GET`` request to my Django
bgneal@4 269 application using a `file_get_contents()`_ call. The PHP can then embed the JSON
bgneal@4 270 directly into the server status page:
bgneal@4 271
bgneal@4 272 .. sourcecode:: php
bgneal@4 273
bgneal@4 274 $ts3_source = 'http://example.com/ts3/';
bgneal@4 275 $ts3_json = file_get_contents($ts3_source);
bgneal@4 276
bgneal@4 277 require_once 'header.php';
bgneal@4 278
bgneal@4 279 And in header.php, some HTML sprinkled with some PHP:
bgneal@4 280
bgneal@4 281 .. sourcecode:: html
bgneal@4 282
bgneal@4 283 <script type="text/javascript">
bgneal@4 284 var ts3_data = <?php echo $ts3_json; ?>;
bgneal@4 285
bgneal@4 286 $(function(){
bgneal@4 287 $("#ts3-tree").dynatree({
bgneal@4 288 persist: false,
bgneal@4 289 children: ts3_data
bgneal@4 290 });
bgneal@4 291 });
bgneal@4 292 </script>
bgneal@4 293
bgneal@4 294 That did the trick. In the end I had to touch a little PHP, but it was
bgneal@4 295 tolerable. That was a very round-about solution to building a TS3 viewer in
bgneal@4 296 Python and Javascript. While I doubt you will have the same strange requirements
bgneal@4 297 that I had (multiple servers), I hope you can see how to combine a few
bgneal@4 298 technologies to make a TS3 viewer in Python.
bgneal@4 299
bgneal@4 300
bgneal@4 301 .. _TeamSpeak 3: http://teamspeak.com/?page=teamspeak3
bgneal@4 302 .. _TS3 query protocol document: http://media.teamspeak.com/ts3_literature/TeamSpeak%203%20Server%20Query%20Manual.pdf
bgneal@4 303 .. _Django: https://www.djangoproject.org
bgneal@4 304 .. _JSON: http://json.org
bgneal@4 305 .. _jQuery: http://jquery.org
bgneal@4 306 .. _dynatree: http://code.google.com/p/dynatree/
bgneal@4 307 .. _python-ts3: http://pypi.python.org/pypi/python-ts3/0.1
bgneal@4 308 .. _same origin policy: http://en.wikipedia.org/wiki/Same_origin_policy
bgneal@4 309 .. _JSONP: http://en.wikipedia.org/wiki/JSONP
bgneal@4 310 .. _file_get_contents(): http://php.net/manual/en/function.file-get-contents.php
bgneal@4 311 .. _TS3 protocol documentation: http://media.teamspeak.com/ts3_literature/TeamSpeak%203%20Server%20Query%20Manual.pdf