Scripting Couch Slouch

Couch Slouch provides an AppleScript dictionary allowing you to drive your AV system from scripts. At the moment, functionality includes: 

  • Turning on the TV.
  • Turning off the TV.
  • Switching the TV’s active source to show the Mac that Couch Slouch is running on.
  • Properties to find out if the TV is on and if it’s showing the Mac as its active source.

For documentation, open the Script Editor application on your Mac, choose Open Dictionary… from the File menu, then choose Couch Slouch from the list of applications. 


This snippet checks if there is an available CEC device connected to your Mac and switches on your TV if it isnt already switched on.

tell application "Couch Slouch”
    if cec device is available and not tv is on then

        turn on tv

    end if

end tell

You can download a more comprehensive example script here.

Scripting AV System Events with Behaviours

Couch Slouch’s Behaviours tab allows you to configure Couch Slouch to perform a task when various events happen in your setup, such as the TV turning on or off, the Mac starting up and shutting down, and so on. 

This section discusses how to use the Behaviours tab to trigger scripts to perform advanced functionality when these events occur.


Script Locations

Script Functions


Important Notes

Script Locations

You can place compiled AppleScript files (.scpt files) into either of the following folders:

  • For the current user only: ~/Library/Application Support/Couch Slouch/Scripts/
  • For all users of the computer: /Library/Application Support/Couch Slouch/Scripts/

Couch Slouch creates the first folder for you, and provides a handy “Open Scripts Folder” button in the Behaviours tab to open it.

Script Functions

Couch Slouch scripts should contain one or more of the following functions, which will be triggered when the desired event occurs. You can create one script that contains all of the functions, have one function per script, or have any combination of scripts/functions you desire. Be aware that your script will only be triggered if it is chosen as the action for the relavent event in the Behaviours tab of Couch Slouch.

  • CouchSlouch_TVOn() — Called when the TV is switched on externally (i.e., not through a Couch Slouch action).

  • CouchSlouch_TVOff() — Called when the TV is switched off externally (i.e., not through a Couch Slouch action).

  • CouchSlouch_BecameActiveTVSource() — Called when the TV switches sources to display the Mac that Couch Slouch is running on.

  • CouchSlouch_LostActiveTVSource() — Called when the TV switches sources away from the Mac that Couch Slouch is running on.

  • CouchSlouch_MacAwoke() — Called when the Mac that Couch Slouch is running on started up and launched Clouch Slouch at login, or woke from sleep.

  • CouchSlouch_MacSlept() — Called when the Mac that Couch Slouch is running on is about to go to sleep or shut down. Note: You only have a very short time to execute before the sleep or shutdown takes effect.


On first launch, Couch Slouch will create an example script in your Scripts folder which demonstrates how everything works, so feel free to take a look at that script and dive right in. If you deleted it or otherwise want another copy, you can download it here.

An AppleScript Function is declared as follows:

on CouchSlouch_TVOn()

    display dialog "The TV was switched on!"

end CouchSlouch_TVOn

If you just want to run a shell script, you can do it like this:

on CouchSlouch_TVOn()

    do shell script "python /path/to/"

end CouchSlouch_TVOn

AppleScript’s do shell script command is detailed in Apple Technical Note TN2065: do shell script in AppleScript.

Important Notes

  • For security, scripts are executed using a helper process rather than directly from Couch Slouch itself.

  • Scripts are executed asynchronously but serially — that is, Couch Slouch will remain responsive to button presses and events while your script is running, but it will only run one script and/or function at a time. If another function is triggered while yours is running, it will be queued up and executed once it has finished. If you have lengthy scripts, this can cause a serious buildup if you’re not careful. If this could be problematic, it may be best to start a new process from your script and return quickly to keep the script queue from building up.

  • If your scripts appear to be not running correctly (or at all), check ~/Library/Application Support/Couch Slouch/Script Errors.log — you’ll find information on any errors that occur in there.

  • Couch Slouch will delay system sleep and system shutdown to allow scripts to execute. However, there’s a system-enforced limit of 30 seconds. Make sure scripts triggered for these events complete in a reasonable amount of time otherwise they’ll be forcefully terminated by the system.


© Daniel Kennett 2018