How Does It Work?
The client application needs to create a TCP (Socket) connection on port 49494. The client application can then send JavaScript and receive back the results of the script. The client application can also make requests for notifications to be sent from Photoshop to the client. These events could be tool changes, document open or close, document changes and others. The full list of Photoshop events along with the information that gets sent to the client can be found at the bottom of this page.
Image data can also be sent back and forth to the client. The image data from any open document can be requested and transferred to the client application. Sending image data from the client to Photoshop will result in a new document being created. The JPEG and Pixmap binary formats are currently supported.
Please note that this is not limited to tablet devices. The communication channel to Photoshop will work with any device or computer that supports the TCP protocol and any language that supports the Socket API. Applications can be written for Blackberry, Windows Phone 7, or Linux devices, though the examples in the SDK are primarily focused on AIR, Android, Java, iOS, and Mac OS.
JavaScript in the Photoshop context
Photoshop uses the JavaScript language for dynamic creation of commands and user interfaces in Photoshop. The Image Processor dialog found under File -> Scripts is an example of a dialog created in JavaScript. The dialog gathers up the configuration, creates commands to process images in a given input folder and puts the processed files in an output folder. This is just one example of the use of JavaScript in the Photoshop context. We point this out so that developers will not confuse JavaScript running inside of Photoshop vs. JavaScript running inside a web page browser application like Firefox.
A developer familiar with the Photoshop Actions panel, running and recording actions and creating Photoshop JavaScripts can move directly to the next section. Developers unfamiliar with actions and/or JavaScript in the Photoshop context should read the JavaScript documentation that comes as part of your Photoshop install. This documentation can be found in the Photoshop Scripting/Documents folder. Open up the Photoshop CS5 Scripting Guide.pdf in Acrobat Reader to become more familiar with how Photoshop uses JavaScript. An online copy of the Scripting documentation can be found here.
Security of your data and messages
All messages to and from Photoshop are encrypted and decrypted. The language selected must also include a key generator and encrypt and decrypt API. The only messages that are not encrypted are error messages. The encryption and decryption algorithms are not configurable. Make sure the encrypt and decrypt API supports the algorithms in use. The current algorithm in use is Password-Based Key Definition (PBKDF2) to generate the key from a given password, iteration count and salt value. DESede + CBC + PKCS5 v2.0 is then used with the key to encrypt and decrypt the message.
Discovery of the connection
Photoshop will advertise as a Bonjour service on the local subnet after being properly configured from the Edit > Remote Connections menu. The service name will be "_photoshopserver._tcp" and the instance name will be configured by the user from the Connections dialog box. Photoshop will automatically remember these settings and start up the service after any restart. Use the dialog box to disable the service.
Connections can also be made if the IP address of the machine is known. The IP address can be found in the Connections dialog box.
Details of data transfered over the TCP connection
This is what you are trying to send:
Notice that the first 8 bytes is not encrypted while the rest of the message isencrypted. The second thing to notice is that if the password is incorrect, the message sent back will not be encrypted. The error message will be sent in plain text in the content section.
Communication Protocol
Bytes |
Description |
|---|---|
4 |
signed length of message, includes everything after |
4 |
communication status, 0 is no error and the remainder of the message is encrypted, non-zero means an error, and the remainder of the message will not be encrypted, probably a password error |
4 |
protocol version number, current version is 1 |
4 |
transaction ID |
4 |
content type, see table below |
variable length |
the actual content, see below |
Content Type
Value |
Description |
|---|---|
1 |
error string, used for errors from server replying to content, should never be sent from client to Photoshop, rest of message is text as UTF-8 |
2 |
JavaScript is used for commands from client to Photoshop, replies from Photoshop will be text, JavaScript and text is always UTF-8 encoded |
3 |
Image, 1 for EXIF standard JPEG format bytes follow for remainder of message, 2 for Pixmap (See table below) |
4 |
ICC profile, not implemented in this version of Photoshop |
5 |
Arbitrary data to be saved as temporary file. The message data will be saved to a temporary file, and the file path for that temporary file is returned. The client should use JavaScript to delete the temporary file when it is done with it. Photoshop will attempt to clean up left over temporary files on a normal exit, but cannot unlink the temporary files as the client may still be using the file. |
Pixmap
Bytes |
Description |
|---|---|
4 |
width of image |
4 |
height of image |
4 |
row bytes of image |
1 |
color mode of image, 1 for RGB currently supported |
1 |
channel count, 1 or 3 currently supported |
1 |
bits per channel, 8 currently supported |
Photoshop Events
Event String |
Extra Data |
Description |
|---|---|---|
foregroundColorChanged |
color value in form of RRGGBB hex value, FF0000 for example |
sent anytime the foreground color gets changed |
backgroundColorChanged |
color value in form of RRGGBB hex value, FF0000 for example |
sent anytime the background color gets changed |
toolChanged |
uniqueToolID, "moveTool" for the Move tool for example |
active tool switched |
closedDocument |
unique id of the document, "45" for example |
document has closed |
newDocumentViewCreated |
unique id of the document |
new view for the document has been made |
currentDocumentChanged |
unique id of document |
active document has changed, this could be from a new document being created or opened |
documentChanged |
unique id of document |
active document has been altered, meaning something has happened to alter the appearence of the document and an image request should be made to the server to get the new apperance |
activeViewChanged |
unique id of document |
active document view has changed |
colorSettingsChanged |
color settings have been modified | |
keyboardShortcutsChanged |
keyboard shortcuts have been modified | |
preferencesChanged |
preferences have been modified | |
quickMaskStateChanged |
quick mask state change | |
screenModeChanged |
screen mode change | |
*any actionable event* |
event ids from 3rd party plug-ins, Photoshop plug-ins or Photoshop |
Events can be requested by the client via a JavaScript message as follows (see the PhotoshopEvents Android example for more details on configuring at runtime):
String s = "var idNS = stringIDToTypeID( 'networkEventSubscribe' );";
s += "var desc1 = new ActionDescriptor();";
s += "desc1.putClass( stringIDToTypeID( 'eventIDAttr' ), stringIDToTypeID( '" + inEvent + "' ) );";
s += "executeAction( idNS, desc1, DialogModes.NO );";
s += "'" + subscribeSuccessStr + "'";
messageProcessor.sendJavaScript(s);