| 1 | Media provider framework |
|---|
| 2 | |
|---|
| 3 | The application will communicate with a media provider over a socket |
|---|
| 4 | connection, this can be an IP socket, a Unix socket, or something else. It is |
|---|
| 5 | important that multiple connections can be established however, so a simple |
|---|
| 6 | pipe might not work. |
|---|
| 7 | |
|---|
| 8 | |
|---|
| 9 | Discovering providers |
|---|
| 10 | |
|---|
| 11 | Providers are discovered by listing all directoties containing them. There will |
|---|
| 12 | generally be a directory in the installation containing system providers, and |
|---|
| 13 | the user profile can also contain a directory with providers. An entry in a |
|---|
| 14 | provider directory can be either an executable file or a text file. |
|---|
| 15 | |
|---|
| 16 | Executable files (known by the .exe extension in Windows, by the execute |
|---|
| 17 | permission bit in Unix) are used as local providers. They will be run and |
|---|
| 18 | queried on application startup, see below. |
|---|
| 19 | |
|---|
| 20 | Non-executable files contain the address of one or more remote servers that can |
|---|
| 21 | be contected and queried. |
|---|
| 22 | |
|---|
| 23 | |
|---|
| 24 | Contacting a local provider |
|---|
| 25 | |
|---|
| 26 | A local provider is, as mentioned, an executable file found in a provider |
|---|
| 27 | directory. To contact a local provider, the executable is launched with |
|---|
| 28 | a command line option specifying a socket provided by the application, that |
|---|
| 29 | the provider must connect to. The connection established here will be the |
|---|
| 30 | control connection for the provider session. |
|---|
| 31 | |
|---|
| 32 | The command line option can be one of: |
|---|
| 33 | |
|---|
| 34 | tcp:<port> |
|---|
| 35 | The application is listening for a TCP/IP connection on the local |
|---|
| 36 | interface, on the specified port number. The port number is given in |
|---|
| 37 | decimal. Example: |
|---|
| 38 | |
|---|
| 39 | tcp:2345 |
|---|
| 40 | The application is listening for a TCP/IP connection on localhost:2345 |
|---|
| 41 | |
|---|
| 42 | unix:<socket> |
|---|
| 43 | The application is listening for a connection on the given Unix socket. |
|---|
| 44 | The socket must be stream-oriented. Example: |
|---|
| 45 | |
|---|
| 46 | unix:/tmp/aegisub-01ab23cd |
|---|
| 47 | The application has created a stream-oriented socket at |
|---|
| 48 | /tmp/aegisub-01ab23cd and is expecting a connection to it. |
|---|
| 49 | |
|---|
| 50 | |
|---|
| 51 | Contacting a remote provider |
|---|
| 52 | |
|---|
| 53 | A remove provider specification file is a plain text file with the address |
|---|
| 54 | of one remote server per line. |
|---|
| 55 | |
|---|
| 56 | The format of a line is the address of the server, a space, and the TCP |
|---|
| 57 | port number it is listening at. The address can be a name, an IPv4 address |
|---|
| 58 | in dotted quad notation, or an IPv6 address enclosed in square brackets. |
|---|
| 59 | |
|---|
| 60 | |
|---|
| 61 | Control connection |
|---|
| 62 | |
|---|
| 63 | The control protocol is text-based and command-oriented, inspired by FTP. |
|---|
| 64 | (Unlike FTP, the protocol is not based on the Telnet protocol.) |
|---|
| 65 | |
|---|
| 66 | All action on the control line is initiated by the application, with the |
|---|
| 67 | provider answering requests. |
|---|
| 68 | |
|---|
| 69 | Requests from the application are one-word commands with zero or more space- |
|---|
| 70 | separated parameters following. |
|---|
| 71 | |
|---|
| 72 | Responses from the provider are numeric response codes followed by details. |
|---|
| 73 | |
|---|
| 74 | The control protocol is used to query available media, open a media, and |
|---|
| 75 | request chunks of the media. The actual media data are transferred on |
|---|
| 76 | auxillary data connections. |
|---|
| 77 | |
|---|
| 78 | |
|---|
| 79 | Data connections |
|---|
| 80 | |
|---|
| 81 | Media data are transferred on one or more auxillary data connections, |
|---|
| 82 | asynchronously from the control connection. Simple provider implementations |
|---|
| 83 | are allowed to block the control connection while data are transferring |
|---|
| 84 | however. |
|---|
| 85 | |
|---|
| 86 | Data connections do not need to use the same communication medium as the |
|---|
| 87 | control connection. One could imagine designing a shared memory |
|---|
| 88 | "connection" for data transfers on the local machine. |
|---|
| 89 | |
|---|
| 90 | Every data connection in a session has an associated number. Data connections |
|---|
| 91 | can be kept alive even when not in use and re-used for subsequent transfers. |
|---|
| 92 | |
|---|
| 93 | Media data transferred on data connections are in binary format, negotiated |
|---|
| 94 | by the application and provider. Generally, this will be an uncompressed |
|---|
| 95 | format, such as PCM for audio, or uncompressed pixel data for video. |
|---|
| 96 | Compression should only be used when necessary, i.e. over a slow network. |
|---|
| 97 | |
|---|
| 98 | Transfers on data connections are always from provider to application, no |
|---|
| 99 | data will be flowing from application to provider. Transfers are initiated |
|---|
| 100 | by requests on the control connection. When the transfer initiates, the |
|---|
| 101 | provider will send a response denoting what data connection it is |
|---|
| 102 | transferring on, and how many bytes are being transferred. |
|---|
| 103 | |
|---|
| 104 | |
|---|
| 105 | Control protocol commands |
|---|
| 106 | |
|---|
| 107 | Command parameters follow these conventions: |
|---|
| 108 | Parameters are separated by one space character. If a parameter value contains |
|---|
| 109 | a space, the value must be enclosed in double quotes. Backslash is the escape |
|---|
| 110 | character, and is used to escape double quotes and other backslashes. |
|---|
| 111 | |
|---|
| 112 | INDEX <resource-name> |
|---|
| 113 | Begin creation of an index for the named resource if it doesn't exist |
|---|
| 114 | already. If an index exists, list all available streams in it. |
|---|
| 115 | |
|---|
| 116 | OPEN <resource-name> <stream-id> [<stream-id> ...] |
|---|
| 117 | Open the given streams in the named resource. All streams required must |
|---|
| 118 | be listed in the OPEN command, further streams can't be opened after |
|---|
| 119 | the resource has been opened initially. |
|---|
| 120 | |
|---|
| 121 | LIST [<directory>] |
|---|
| 122 | Only allowed for providers that do not use the local file system. |
|---|
| 123 | Lists all resources in the given directory, or the root of the resource |
|---|
| 124 | tree is no directory is specified. |
|---|
| 125 | |
|---|
| 126 | GETOPT [<name>] |
|---|
| 127 | Get the value of the named option. If no option name is given, list all |
|---|
| 128 | known options and their values. |
|---|
| 129 | |
|---|
| 130 | SETOPT <name> [<value>] |
|---|
| 131 | Set the named option to the given value. |
|---|
| 132 | The provider may reject the change if the value is out of range or |
|---|
| 133 | otherwise invalid. |
|---|
| 134 | If no value is given, the option is reset to the default value. |
|---|
| 135 | |
|---|
| 136 | NEWDC <protocol> [options...] |
|---|
| 137 | Create a new data connection. The protocol can be "tcp", "unix" or |
|---|
| 138 | something else, and the options depend on the protocol. |
|---|
| 139 | The provider must attempt to connect to the socket the application is |
|---|
| 140 | listening on, and respond with the new connection id when it succeeds, |
|---|
| 141 | or respond with failure otherwise. |
|---|
| 142 | |
|---|
| 143 | CLOSEDC <connection-id> |
|---|
| 144 | Close the given data connection. |
|---|
| 145 | |
|---|
| 146 | GETDATA <stream-id> <connection-id> <start> [<end>] |
|---|
| 147 | Request media data from the given stream number to be sent on the given |
|---|
| 148 | data connection. The start is the first frame number to transmit. |
|---|
| 149 | If no end is given, only the start frame is transmitted, otherwise all |
|---|
| 150 | frames from start up to and including the end frame are transmitted. |
|---|
| 151 | For audio, frame numbers are sample numbers. |
|---|
