Media provider framework The application will communicate with a media provider over a socket connection, this can be an IP socket, a Unix socket, or something else. It is important that multiple connections can be established however, so a simple pipe might not work. Discovering providers Providers are discovered by listing all directoties containing them. There will generally be a directory in the installation containing system providers, and the user profile can also contain a directory with providers. An entry in a provider directory can be either an executable file or a text file. Executable files (known by the .exe extension in Windows, by the execute permission bit in Unix) are used as local providers. They will be run and queried on application startup, see below. Non-executable files contain the address of one or more remote servers that can be contected and queried. Contacting a local provider A local provider is, as mentioned, an executable file found in a provider directory. To contact a local provider, the executable is launched with a command line option specifying a socket provided by the application, that the provider must connect to. The connection established here will be the control connection for the provider session. The command line option can be one of: tcp: The application is listening for a TCP/IP connection on the local interface, on the specified port number. The port number is given in decimal. Example: tcp:2345 The application is listening for a TCP/IP connection on localhost:2345 unix: The application is listening for a connection on the given Unix socket. The socket must be stream-oriented. Example: unix:/tmp/aegisub-01ab23cd The application has created a stream-oriented socket at /tmp/aegisub-01ab23cd and is expecting a connection to it. Contacting a remote provider A remove provider specification file is a plain text file with the address of one remote server per line. The format of a line is the address of the server, a space, and the TCP port number it is listening at. The address can be a name, an IPv4 address in dotted quad notation, or an IPv6 address enclosed in square brackets. Control connection The control protocol is text-based and command-oriented, inspired by FTP. (Unlike FTP, the protocol is not based on the Telnet protocol.) All action on the control line is initiated by the application, with the provider answering requests. Requests from the application are one-word commands with zero or more space- separated parameters following. Responses from the provider are numeric response codes followed by details. The control protocol is used to query available media, open a media, and request chunks of the media. The actual media data are transferred on auxillary data connections. Data connections Media data are transferred on one or more auxillary data connections, asynchronously from the control connection. Simple provider implementations are allowed to block the control connection while data are transferring however. Data connections do not need to use the same communication medium as the control connection. One could imagine designing a shared memory "connection" for data transfers on the local machine. Every data connection in a session has an associated number. Data connections can be kept alive even when not in use and re-used for subsequent transfers. Media data transferred on data connections are in binary format, negotiated by the application and provider. Generally, this will be an uncompressed format, such as PCM for audio, or uncompressed pixel data for video. Compression should only be used when necessary, i.e. over a slow network. Transfers on data connections are always from provider to application, no data will be flowing from application to provider. Transfers are initiated by requests on the control connection. When the transfer initiates, the provider will send a response denoting what data connection it is transferring on, and how many bytes are being transferred. Control protocol commands Command parameters follow these conventions: Parameters are separated by one space character. If a parameter value contains a space, the value must be enclosed in double quotes. Backslash is the escape character, and is used to escape double quotes and other backslashes. INDEX Begin creation of an index for the named resource if it doesn't exist already. If an index exists, list all available streams in it. OPEN [ ...] Open the given streams in the named resource. All streams required must be listed in the OPEN command, further streams can't be opened after the resource has been opened initially. LIST [] Only allowed for providers that do not use the local file system. Lists all resources in the given directory, or the root of the resource tree is no directory is specified. GETOPT [] Get the value of the named option. If no option name is given, list all known options and their values. SETOPT [] Set the named option to the given value. The provider may reject the change if the value is out of range or otherwise invalid. If no value is given, the option is reset to the default value. NEWDC [options...] Create a new data connection. The protocol can be "tcp", "unix" or something else, and the options depend on the protocol. The provider must attempt to connect to the socket the application is listening on, and respond with the new connection id when it succeeds, or respond with failure otherwise. CLOSEDC Close the given data connection. GETDATA [] Request media data from the given stream number to be sent on the given data connection. The start is the first frame number to transmit. If no end is given, only the start frame is transmitted, otherwise all frames from start up to and including the end frame are transmitted. For audio, frame numbers are sample numbers.