summaryrefslogtreecommitdiffstats
path: root/soundserver/kmedia2.idl
blob: 96fd5a0fc51e4d54c7c0007aa5f821932eedfcc5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
/*

NEW KMedia2 tqlayout:
===================

KMedia1 itself doesn't play anything. Instead it has a backend for every
media type to play. It tells these backends: "start playing now", "stop
playing now" and similar things (using libmediatool). So there is a backend
for wave files, tacker files, midi files, etc., which all provide one
common interface.

The idea is to keep everything the old KMedia1 interface could do, but to
move to a new IPC architecture (MCOP).

That way, KMedia2 objects will be able to use the aRts streaming abilities.
Of course, not every KMedia2 object will need these, but some of them. The
result will be much nicer, if every of these objects can be treated in the
standard "flow graph" way, like other aRts objects can.

The ultimate media player, which KMedia2 aims to be, should play midi,
video, audio, etc. It is about seeing a file, choosing a component which
might be able to decode it, and play it. So it is not about starting
the right application, but about loading the right component.

This gives you the advantage that you can for instance reuse components
even between quite different media types. It may for instance make sense
to reuse a reverb effect to play midi, audio and video files.

*/

#include "artsflow.idl"

module Arts {

enum poState {
  posIdle,
  posPlaying,
  posPaused
};

// use 2^n values here, since they can (should) be or'd together
enum poCapabilities {
  capSeek = 1,
  capPause = 2
};

/**
 * KMedia2 time information
 *
 * This is a time value which contains either milliseconds & seconds, or
 * a custom unit or both. It is a flexible time base.
 *
 * If a value isn't there, it is set to -1.
 */
struct poTime {
	/**
	 * time it takes in seconds; -1 if no clock time known
	 */
    long seconds;

	/**
	 * additional time in milliseconds (this doesn't contain all the time)
	 * -1 if no clock time known
	 */
	long ms;

	/**
	 * some custom time information
	 * -1 if no custom time known
	 */
    float custom;

	/**
	 * for instance for a tracker "pattern"
	 */
    string customUnit;
};

/**
 * private part of the PlayObject API (don't use)
 */
interface PlayObject_private {
	/**
	 * loads a file
	 */
	boolean loadMedia(string filename);
};

/**
 * KMedia2 PlayObject - these can be used by Kaiman for instance
 */
interface PlayObject : PlayObject_private {
    readonly attribute string description;
    readonly attribute poTime currentTime;
    readonly attribute poTime overallTime;
    readonly attribute poCapabilities capabilities;
    readonly attribute string mediaName;
    readonly attribute poState state;

	/**
	 * starts playing the media
	 */
    void play();
	/**
	 * seeks to a specific time
	 */
    void seek(poTime newTime); // could be handled by setting currentTime
	/**
	 * pauses playing the media
	 */
    void pause();
	/**
	 * stop playing the media. Normally this function would called stop,
	 * but the name is reserved for the start/stop mechanism of the
	 * aRts objects.
	 */
    void halt();
};

/**
 * use this to create new PlayObjects for media
 */
interface PlayObjectFactory {
	/**
	 * creates a play object (or returns a null reference if this is not
	 * possible)
	 *
	 * @param filename the name of the file to create a play object for
	 */
	PlayObject createPlayObject(string filename);
};

/**
 * UNSTABLE/EXPERIMENTAL!
 */
interface InputStream : SynthModule {
	/**
	 * whether the stream is at the end of the input
	 */
	readonly attribute boolean eof;

	/**
	 * total size of the stream in bytes
	 *  -1: unknown
	 */
	readonly attribute long size;

	/**
	 * whether the stream can be seeked
	 */
	readonly attribute boolean seekOk;

	/**
	 * this returns the new AGE of the stream, where AGE is defined as the
	 * number of bytes that have been sent since the stream exists
	 */
	long seek(long position);

	/**
	 * the stream data
	 */
	async out byte stream outdata;
};

/**
 * UNSTABLE/EXPERIMENTAL! Example stream for files.
 */
interface FileInputStream : InputStream {
	attribute string filename;

	boolean open(string filename);
};

interface StdoutWriter : SynthModule {
	async in byte stream indata;
};

interface StreamPlayObject : PlayObject {
	/**
	 * prepares the playobject for the stream
	 */
	boolean streamMedia(InputStream instream);

	/**
	 * last used inputstream
	 * it should never change
	 */
	 InputStream inputStream();
};

/**
 * Playobject with adjustable speed
 */
interface PitchablePlayObject {
	/**
	 * speed relative to "original"/intended one
	 * (1.0=normal, 2.0=double ;-), 1.05=5% faster)
	 */
	attribute float speed;
};

/**
 * KMedia2 VideoPlayObject - new interface for video support
 *
 * Some of the communication is done using the X11 protocol.
 */
interface VideoPlayObject {
    /**
     * video output window (active)
     */
    attribute long x11WindowId;
    /**
     * take a snapshot and draw it onto a pixmap
     * returns the X11 pixmap ID or -1 on error
     */
    long x11Snapshot();
};

/**
 * Extended Version of PlayObjectFactory
 */
interface PlayObjectFactoryV2 : PlayObjectFactory {
	/**
	 * creates a PlayObject
	 *
	 * @param url the url to create a play object for
	 * @param mimetype mimetype for the url
	 * @param createBUS specifies wheter to create the bus-uplink or not
	 */
	PlayObject createPlayObjectForURL(string url, string mimetype, boolean createBUS);

	/**
	 * creates a StreamPlayObject (used internally!)
	 *
	 * @param instream specifies the InputStream
	 * @param mimetype mimetype for the InputStream
	 * @param createBUS specifies wheter to create the bus-uplink or not
	 */
	PlayObject createPlayObjectForStream(InputStream instream, string mimetype, boolean createBUS);
};

};