Tuesday, August 14, 2018

Commanding Laserdiscs

Coming soon...
For the past couple evenings, I've been poking at controlling video playback programmatically... I was inspired by Kevin Savetz' recent project to resurrect the Rollercoaster Apple ][ Laserdisc game.  He got it working, fixed it, enhanced it to work for the DVD version of the game, and was showing it off at KansasFest.

My first quick hack, as seen before on this blog, was to screen-scrape an Infocom game (Hitchhiker's Guide to the Galaxy), and based on text from that, force VLC to play back certain frames or tracks of video from the Hitchhiker's Guide TV show.

I've been poking at actually making Rollercoster be playable inside the browser for my next trick. I'm basing it all on the source code, which Kevin has made available to us, and using a HD transfer of the movie, which hopefully is the same edit of the film as the Discovision Laserdisc.

There will be more on this later, but the short version is that I'm using jsbasic to run Applesoft Basic right in the browser (no emulation of an Apple ][ ), simulating the Super Serial port (6551 ACIA chip), capturing the BASIC game's laserdisc commands being sent to said serial port, and then using that information to control a fakeo-laserdisc player, which is just an HTML 5 video player.  I'm still working through all of this.  The cool thing is that when I'm done with this, it could be a great test system for people wanting to make more LD-AppleII games.  As long as you use video files that can be properly frame-associated with real discs, it should be a drop-in kind of thing.

NOTE: if I learn more information, I'll note it in this post.  I'm really green when it comes to Apple II hardware, and really Apple II programming in general. This is really my first deep-dive into Apple II serial hardware and specifics of Applesoft BASIC!

Super Serial card

The Super Serial for this game is in slot 2, and is fitted with a 6551 ACIA serial interface chip. Writes to the ACIA get sent out immediately, they are not buffered.  The ACIA has one bit on its status port 0x08 or b00001000 that goes high when there's a byte to read.  The LDP will send a 'R' when its current task is complete.

The Super Serial card, being in slot 2 means that its four registers are at decimal locations:

  • 49320 - Data 
    • Read from here to read characters sent to the Apple
    • Write to this to send out characters to the LDP
  • 49321 - Status
    • Read from here to get error codes, 
    • Read and mask off 0x08 to get the "is a character ready to be read from the LDP?
  • 49322 - Command
  • 49323 - Control
    • These two are used to configure the port, for baud rate, parity, etc.  For this project, I'm simulating the behavior of the device at a very high level, so i basically ignore all of this stuff.
    • The real hardware runs at 4800 baud, 8-N-1
This means that to write a character (newline) out to the LDP:
  • POKE 49320,13

LDP Simulation

Anyway. there's been some interest in others wanting to simulate the Laserdisc player (LDP) using other methods (using VLC for example), so I thought I'd just do a quick post to explain my current understanding of the specific commands used by the game. You can look up specifics of the protocol in the LD-V4400 User's Manual, or in the DVD-V8000 User's Manual  All commands are two-letter sequences, uppercase (although the manual says that it accepts lowercase as well.) and can have a number BEFORE the opcode.

There are a lot of commands that these can handle, but these are the commands that we care about for this game:

Go into "frame mode".  This means that any addresses will be in number of frames from the start of the disc.  Frame 0 is the first frame on the disc, the final frame is dependent on the duration of the disc.  CAV discs are about 30 minutes of content. at 29.97FPS (NTSC), that is roughly 54,000 frames.

(address) SE
Seek to the address (frame number) and go into still-frame mode.  Reading from the ACIA, 

(address) PL
Play, and go to still-frame mode when the address (frame number) is reached.

Additionally, the game's command strings use '/' to indicate a carriage return (CR) character, which is sent as decimal value 13.  The player will then execute the command, and will send back an "R" character (decimal 82) when it completes.

Let's go through a couple real examples...

  • Switch the LDP into frame mode
  • Seek to frame 2818, and still-frame there
  • LDP will send "R" when it has completed.
AKA: Still frame on frame 2818, will send "R" when done.

  • Switch the LDP into frame mode
  • From the current position, play until the frame number reaches 2134, and still-frame there
  • LDP will send an "R" when it has completed
AKA: Play until frame 2134, will send "R" when it reaches there.

  • Switch the LDP into frame mode
  • Seek to frame 6726, and stillframe
  • LDP will send "R" when ready
  • (switch to frame mode)
  • Play until frame 6959, and then stillframe
  • LDP will send "R" when ready
AKA: Play from frame 6726 through 6959, send "R" when done.

Game implementations

The serial port configuration and setup is at line 31000.  The sequence it does is that it POKEs 11 to 49322, and 28 to 49323, which sets up the serial port configuration (baud, parity, etc).  It also does something with CHR$(4); "PR#2" or "PR#0".  I'm honestly not entirely sure what those are for, something with sending data to the serial card.

The BASIC code to send the command strings is at line 40000, and the command string is stored in VC$.  So in the program you'll see stuff like:
34000 VC$ = "FR2818SE/": GOSUB 40000 
34011 VC$ = "FR6726SE/FR6959PL/": GOSUB 40000
You already know what these do from the above examples!

The LDP communication code at 40000 is:
40020  FOR I = 1 TO  LEN (VC$)
40030  IF  MID$ (VC$,I,1) = "/" THEN  POKE 49320,13: WAIT 49321,8:J =  PEEK (49320): GOTO 40060
40040  POKE 49320, ASC ( MID$ (VC$,I,1))
40060  NEXT I
40070  RETURN
Or, in human readable terms:
  • if "DISC" is set 0, then there's no VDP, so just return
  • For each character of the command string:
    • if the character is a '/', then send the VDP a carriage return, and wait for "R" response
    • otherwise just send the current command string character to the VDP

The code also uses the "WAIT" command, which was not implemented in the javascript library I was using.  This command essentially blocks, and waits until the conditions are met.  In the above code it essentially is PEEKing at 49321 (ACIA status) for bit 8 to be set; for a character to be ready to read in.. It then reads the character to variable J, which is then ignored. ;)  But it knows the LDP is done with the task.

Friday, August 10, 2018

4 Hour Projects: Adding Video to Interactive Fiction


After listening to the Eaten By A Grue podcast:19 about the interactive laserdisc-based game for the movie "Rollercoaster", and then following that up with the episode about Hitchhiker's Guide:16, a spark popped in my head. It should be possible to somehow "watch" the Hitchhiker's Guide (H2G2) Infocom game and play clips of the TV show, movie, etc, syncronized to the scenes and what you're looking at.
All of the distributable code for this is available at the github page for the project.
Just about all of this project is based on existing stuff, but I glued it all together.
  • Frotz - runs the Z-code, in a text-based terminal
  • VLC media Player - plays back the video
  • H2G2 TV on DVD - the DVDs
  • Netcat - so my client can talk to the server
  • Tee - to split the output from frotz
  • Perl script (in this repo) - "reads" the text, matches text, tells VLC what to play
The whole thing kinda works, is buggy, unoptimized, but that's the nature of a 4 hour hack.


This is the basic system... This was a quick sketch I made to get the idea down. Essentially there are two halves. (I also called it "zvid" instead of "llifvid". pls ign. thx.)

Server/Video player

The server on the left is essentially a perl script that:
  • Matches text from the interactive fiction
  • has a simple interpreted language that can perform sequential functions
  • outputs "remote" commands for VLC
The output of that perl script is piped into VLC. If you're going to reproduce this, be aware that enabling the VLC shell it was a bit tricky, and I didn't document the process. I think I needed to enable extended preferences in VLC to see the bit to turn on that feature.
Also on this side are the video files for H2G2 episodes 1 and 2. I used Handbrake to decode them off of my DVDs. I do know that the episodes exist online, but those may be set up for web streaming, and will need to be transcoded via handbrake or some other tool. It basically just needs to add some information in that isn't there.
Netcat (nc) is setup as a listener for the text output from the game engine. That is piped into the perl script, whose output is piped into VLC.

Client/Game engine

The client on the right is some bash script piping and connection of Frotz with the game file. I used the ms-dos version of the data file, although I do not know if any other versions differ in any way. This was just easiest for me to grab without digging out and setting up my Amiga to pull the files off of my game's floppy.
The output of frotz is piped through tee. Tee takes the output and splits it to two different places. First, is the console so you can see what you're doing, but it also usually saves it to a file. I've changed that path to be piping the output to netcat, setup as a transmitter to the server.


In the perl script is a quick interpreter that I hacked together to run little micro scripts of code. I started doing this as an array of arrays, but if you've ever done that in perl, you'd know that such things are never good ideas in that language. I briefly considered hopping over to python to do it, but I already had stuff done, and was still toying with the idea of having the perl script itself listening to a socket, which i was unsure of how to do in python. So it's in perl.
Anyway, I switched it over to be a plain text blob in the source file. At startup, it cleans up the text, removing comments, and empty lines. It also breaks it up as two elements per line; the opcode and the parameter, and store that as the runtime program. This vastly simplified runtime routines.
The two main entry bits for the language are the label and the text match. It's sort of event driven, sequential language, with no nesting, no calls, no iterations, none of that... one operation per line. I did include comments though which are denoted by pound sign, # and continue to the end of the line. They can be put anywhere, as they are filtered out before runtime.
: label
Labels are used for 'goto' statements, or calling the goto function to set the current PC (program counter). If you call the doGoto() function, it will adjust the PC to the line after that label, or to -1, indicating that it was not found, and there's nothing to do.
? text to match
This denotes text that should be matched. As the program runs, it reads in byte by byte from the client and accumulates it. When it hits a newline 0x0d, or 0x0a, it sends the accumulated text to the "got a line" function. That one tries to match each "text to match" string to see if it matches any part of the current line. If it does, it sets the PC to the next line, and returns.
From there, there are a few opcodes that can be called:
seek 100
This will seek the current video file to 100 seconds in.
until 110
This will wait until the timer hits 110 seconds in in the video. Due to limitations of time, this is implemented as a hack. Instead of looking at the video file to get the time, it remembers the last 'seek' number called, does a difference, and sleeps for that many seconds, blocking. For the above two codes the "until 110" call will essentially sleep for 10 seconds
Indicates that a sequence of opcodes is done. "do until done" will stop here" this leaves the PC at -1, indicating it's done.
player play
This sends the "play" command to VLC. It can send anything. Useful things are:
play    # press play on the current videopause   # toggle pause!frame   # advance one frame. forces a paused statestop    # stops the playerfullscreen on  # makes the video full screen (on|off)seek 100 # you can manuall call this as wellrate 2   # twice speed... or "0.25" for quarter speed. etcadd FILENAME   # adds a file to the playlist, and switches to it
These essentially just print out the command, as the VLC shell is consuming the commands directly.

Determining match strings

For this I basically ran "frotz hhg.z3" and copy-pasted long lines of text from the game to match that seemed unique. It worked okay but was kinda tedious.
I was originally going to extract out the room names/descriptions from the z3 files using the tools, but gave up on that for this simpler, quicker approach.

Determining timing

So to get the second counts, I ran VLC, playing the video file, directly: "vlc episode1.m4v", and did a lot of typing in the shell of the above commands. I would type "play" to let it play, then "pause" or "frame" to get it to stop. You can get the current time with "get_time", manually seek to specific times like "seek 300" or differences from the current time, "seek -10" for ten seconds ago, etc.
I could use the GUI for this, but it shows time as mm:ss rathe than time as seconds only.
It was tedious, but it worked. An easier to use mechanism for this would be advantageous.


So yeah... it worked.  With a lot more work it could be made to be reliable, have a nice editor, and be easily streamlined into more games.  I'd personally want to see an integrated executable as well, to get rid of all of this netcat and shell weirdness, and just have one exe that runs, reading in a language file.  Game packages could be created with the language file, audio, video, etc.  But I feel like I've accomplished what I wanted to for this.