Media Control Stack
ERS Version 1.0d2

Last Revision Wednesday, October 2, 1991




Media Control Stack Description
The Media Control stack (hereafter referred to as the MC stack) allows 
the user to control a wide variety of interactive media devices from 
HyperCard IIGS version 1.1.  Interactive media devices are most 
clearly typified by CD-ROM drives and LaserDisc players although 
certain other types of devices such as VCRs may contain a hardware 
interface through which they can be controlled by a computer.

The MC stack controls these devices by interfacing with the Media 
Control Tool which will be shipping with Apple IIGS System 6.0 and is 
required to use this stack.  The MC stack also provides options to 
work with the Apple II Video Overlay card.


Media Control Stack Implementation
The MC stack is one of two totally new stacks shipping with HyperCard 
IIGS version 1.1.  The stack will reside on the HyperTalk Help disk 
and be installed into a folder called Stacks along with the rest of 
the stacks shipping with HyperCard IIGS version 1.1.  The Home stack 
has been extended to include a link to this stack through the Tool Kit 
card.  The MC stack is less than 100K in size.

The MC stack, like the rest of the HyperCard IIGS shipping stacks and 
HyperCard IIGS itself, provides several levels of involvement and 
complexity for the user.  Users who wish to play laser discs, CDs, 
etc. may use the built in Media Control window to control these 
devices from the Media Control stack or from any other stack.

                                                     
Open File "Media.1" to see Figure 1 - Media Control Window

For those users wishing to create their own stacks but who are not 
accomplished HyperTalk scripters, the stack provides a card of ready-
made buttons which can be pasted into their own stacks and used 
without modification.

The final level available to those who wish to script in HyperTalk are 
the scripts of the ready-made buttons which can be examined for 
examples of how to access the features of the Media Control XCMD.  
Also available is a card which lists all features and syntax to use 
them of the Media Control XCMD.  The MC stack will install this XCMD 
in any stack of the user's choosing, just as in the Scripter's Tools 
stack.

The Media Control XCMD
The Media Control XCMD provides a HyperCard interface to the commands 
available with the Media Control tool.  The commands presented to the 
user have been kept as close as possible to the syntax and structure 
of the Media Control tool commands but with regard to the different 
audience who will be generally using the XCMD (scripters) as compared 
to the tool (programmers).  For example,while the tool requires time 
parameters to be input as BCD time values, the XCMD allows time in the 
format "hh hours, mm minutes, ss seconds."

Media Control XCMD Commands
The following section details the commands available through the Media 
Control XCMD.


Media Control Command - "Control"
Syntax:
     MediaControl <channel>, "Control", <cmd>

This powerful command provides access to many aspects of the Media 
Control Toolset including audio output configurations and 
communication parameters. The following subcommands are available:
     Serial port subcommands
     8data1stop, 8data2stop, 7data1stop, 7data2stop, 6data1stop, 
6data2stop
     5data1stop,5data2stop
     BaudDefault, Baud50, Baud75, Baud110, Baud134, Baud150, Baud300,
     Baud600, Baud1200, Baud1800, Baud2400, Baud3600, Baud4800, 
Baud7200
     Baud9600, Baud19200
     ControlCom, ModemPort, PrinterPort

     Audio channel subcommands
     AudioLeft, AudioLinLR, AudioLinLMR, AudioLinR, AudioMinL, 
AudioMinLLinR,
     AudioMinLRinR, AudioMinR, AudioMonaural, AudioOff, AudioReverse,
     AudioRight, AudioRinL, AudioRinLMR, AudioRinLR, AudioStereo

     Video subcommands
     DisplayOff, DisplayOn, VideoOff, VideoOn

     Miscellaneous subcommands
     Eject, IgnoreDiskSwitched, Initialize, LockDevice, 
ReportDiskSwitched, UnlockDevice


Media Control Command - "GetDiscID"
Syntax:
     MediaControl <channel>, "GetDiscID"

This command returns a unique ID for the currently running disc in the 
global variable MediaResult.  For a CD, this value is the total number 
of blocks or the serial number if available. 


Media Control Command - "GetDriverName"
Syntax:
     MediaControl <channel>, "GetDriverName"

This returns the name, version, and port used for the device driver 
currently connected to the specified channel in the global variable 
MediaResult.

MediaResult will contain the text "NoPlayer" if no device driver is 
connected to the specified channel.  

Media Control Command - "GetNumTracks"
Syntax:
     MediaControl <channel>, "GetNumTracks"

This command returns the number of tracks/ chapters on the media in 
the device connected to the specified channel.  The value will be 
returned in the global variable MediaResult. 


Media Control Command - "GetPosition"
Syntax:
     MediaControl <channel>, "GetPosition", 
"InChapters|InFrames|InTime"

This command returns the current position of the specified device. 
This number will be returned in MediaResult if "InChapters" or 
"InFrames" is selected.  If you specify "InTime", the location will be 
returned in the form "hh hours, mm minutes, ss seconds" if the current 
device supports this.


Media Control Command - "GetSpeeds"
Syntax:
     MediaControl <channel>, "GetSpeeds"

This returns a comma delimited list of speeds (in frames per second) 
that the device connected to the specified channel can play.  The list 
of speeds is returned in the global variable MediaResult.  CD-ROM 
drives do not generally support this command.


Media Control Command - "GetStatus"
Syntax:
     MediaControl <channel>, "GetStatus", 
"DeviceType|PlayStatus|DoorStatus|
     DiscType|DiscSize|DiscSide"

This command enables you to determine the status of a device connected 
to the specified channel.  The third parameter determines what type of 
status is returned in the global variable MediaResult.


Media Control Command - "GetTimes"
Syntax:
     MediaControl <channel>, "GetTimes", 
"ElapsedTrack|RemainTrack|ElapsedDisc|
     RemainDisc|TotalDisc|TotalFrames|Tracks"

This command returns information about the currently playing media 
including total time, remaining time, starting and ending track 
numbers, and total frames.  Time is returned in the form "hh hours, mm 
minutes, ss seconds."


Media Control Command - "JogBackward"
Syntax:
     MediaControl <channel>, "JogBackward", 
"InChapters|InFrames|InTime",      <amount>

This command moves the specified device backward.  If moving by 
chapter or frame, <amount> contains the number of frames or chapters 
to move.  If moving backward in time, <amount> contains the amount of 
time in the form "hh hours, mm minutes, ss seconds."


Media Control Command - "JogForward"
Syntax:
     MediaControl <channel>, "JogForward", 
"InChapters|InFrames|InTime",      <amount>

This command moves the specified device forward.  If moving by chapter 
or frame, <amount> contains the number of frames or chapters to move.  
If moving forward in time, <amount> contains the amount of time in the 
form "hh hours, mm minutes, ss seconds."


Media Control Command - "Pause"
Syntax:
     MediaControl <channel>, "Pause"

This command will put the device specified by <channel> into pause 
mode if it is currently playing.  Playing can be resumed with the Play 
command. 


Media Control Command - "Play"
Syntax:
     MediaControl <channel>, "Play"

This command starts the device playing forward at normal play speed.


Media Control Command - "Record"
Syntax:
     MediaControl <channel>, "Record"

This command initiates record mode if the specified device has that 
capability.


Media Control Command - "Remote"
Syntax:
     MediaControl "Remote"

This command creates and displays a movable window from which you can 
perform many of the basic Media Control commands.  It will remain open 
and active until you click its close box, close it from HyperTalk, or 
exit HyperCard.  This window can be used to control interactive media 
devices while in other stacks.  Commands are sent to the channel 
specified by the MediaChannel global variable.


Media Control Command - "ScanBackward"
Syntax:
     MediaControl <channel>, "ScanBackward"

This causes the device connected to the specified channel to scan 
backward.  The results of this command are device dependent.  Some 
devices, notably the Apple CDSC drive, will scan backward until 
stopped with another command.  Many laserdisc players will scan a 
short distance and stop.


Media Control Command - "ScanForward"
Syntax:
     MediaControl <channel>, "ScanForward"

This causes the device connected to the specified channel to scan 
forward.  The results of this command are device dependent.  Some 
devices, notably the Apple CDSC drive, will scan forward until stopped 
with another command.  Many laserdisc players will scan a short 
distance and stop.


Media Control Command - "SearchTo"
Syntax:
     MediaControl <channel>, "SearchTo", 
"InChapters|InFrames|InTime", 
     <location>

This command moves the specified device to <location>.  If moving by 
chapter or frame, <location> contains the frame or chapter number 
requested.  If "InTime" is specified, <location> contains the time 
requested in the form "hh hours, mm minutes, ss seconds."


Media Control Command - "SetSpeed"
Syntax:
     MediaControl <channel>, "SetSpeed", <fps>

This causes the connected device to play at the specified number of 
frames per second <fps>.  The device will play at this speed the next 
time it receives a play command.  The frame speed is reset to normal 
(30 fps) after each play command.  Use the GetSpeeds command to 
determine what speeds are available for a particular device.


Media Control Command - "Stop"
Syntax:
     MediaControl <channel>, "Stop"

This command stops the device connected to the specified channel.  
After this command, some devices will resume play at the current 
location while others will return to the beginning of the media. 


Media Control Command - "StopAt"
Syntax:
     MediaControl <channel>, "StopAt",  "InChapters|InFrames|InTime", 
<stopLoc>

This command sets the location at which the specified device will stop 
playing.  If setting the stop location to a chapter or frame, 
<stopLoc> contains the frame or chapter number.  If setting the stop 
location to a particular time, <stopLoc> contains the time in the form 
"hh hours, mm minutes, ss seconds."


Media Control Command - "VideoOverlay"
Syntax:
     MediaControl "VideoOverlay", "on|off"

This command enables or disables the video overlay feature of the 
Apple II Video Overlay Card.





Cards in the Media Control Stack
The following are screen shots of the five cards in the MC stack.

                                            
Open File "Media.2" to see Figure 2 - Media Control Stack Menu Card


                                            
Open File "Media.3" to see Figure 3 - Media Control Stack Commands Card


                                            
Open File "Media.4" to see Figure 4 - Media Control Stack ReadyMade Buttons Card


                                            
Open File "Media.5" to see Figure 5 - Media Control Stack Video Overlay Card


                                            
Open File "Media.6" to see Figure 6 - Media Control Stack Information Card