| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
Both audio (/dev/dsp*) and MIDI (/dev/midi*) devices support the song_name and label tag mechanism. With this mechanism the application using the device can tell what it's doing. Other applications can read these tags and use the information as they like.
Even this interface is not supported by other than audio or MIDI devices at this moment it's possible that this changes in the future OSS versions. For this reasons even applications using other types of devices (/dev/mixer*) may try to set the label tags if there is any meanigfull use for them.
Note that this tag mechanism is optional feature. Not all devices or OSS implementations support it. Also it only works if the application using the device supports it. An empty tag string means that this information is not available.
The tag strings can be accessed using the following (new) ioctl calls:
The SNDCTL_AUDIOINFO and SNDCTL_MIDIINFO calls can be used by any applications to find out the strings for the devices. For example the ossinfo
utility shows that info. The other calls can only be used by the application that is using the particular device.
The way how the meta tabs work depends on the type of the device. However the applications using these tags should in no case try to determine the device type and to use different policies depending on it. Usage of these tag strings must be exactly the same regardless of the device type.
With most of the "ordinary" physical devices these tags don't have any significant meaning. The application using these tags may set them and all applications using the SNDCTL_AUDIOINFO and/or SNDCTL_MIDIINFO calls will see them. For example a mixer program may use the label tag as a the label of an control element (slider) which makes the user interface more useful.
In some cases it may also be possible to communicate these tags between the computer and the audio/MIDI devices connected to it. For example a tape recorder may return the label of the tape it's currently reading. The application "receiving" the tape may use the tape label as a file name in some computer archive.
The meta tags will in general be more usefull with all kind of virtual devices. One particularily important example is the MIDI loopback driver (Bad xlink 'MIDILOOP'). Loopback devices are virtual devices that don't drive any hardware. Instead they are just communication pipes that connect two applications together. Both applications think they are talking to real hardware while they are in fact talking to each other.
For example a software synthesizer application (such as softsynth_gtk.c ) can listen the server side of the loopback device. When a MIDI player application opens the client side it can set the song name tag (using SNDCTL_SETSONG). The server side application can read the song name tag using SNDCTL_GETSONG and show it on it's status display.
Applications using the meta tag strings should behave like they are using a loopback device. They should use the SNDCTL_SETSONG and SNDCTL_SETLABEL ioctl calls to set the songname and label tags. However they shall do it only if they have something meaningfull info to show. It's better to leave these tags empty rather than use some hardcoded strings such as "dummy", "myapp" or "Unknown song". Setting the tags unnecessarily will prevent the "remote" application or OSS from giving some better value to the tags.
If a device doesn't support tags these ioctl calls will return an error (errno=EINVAL). However this is not an error at all. It simply means that there is no need to set this particular tag. Applications must in no case report an error (or even warning) when this happens.
Preferably applications should set the song name and label tags only if requested by the user (using command line switches or some other configuration settings).
An application can use the SNDCTL_GETSONG and SNDCTL_GETLABEL calls to check if the "remote" end has assigned these tags. If the tag string is empty then there is no tag assigned by the remote end (source). The situation may change after few moments so the application should poll the tags (say) once per 10 seconds (too tight polling is not recommended). If the ioctl call returns an error (errno=EINVAL) then the device doesn't support this tag. This is in no way an error. The application just should not try to read the same tag again. Otherwise it should behave just like with empty tags.
It's very important to understand that the value returned by the SNDCTL_GETxxxx call will never be the same as the one written by the previous SNDCTL_SETxxxx call (OTOH this may happen randomly). The SNDCTL_GETxxxx calls return whatever tag was assigned by the remote end.
These calls work in both ways regardless of the mode flags (O_WRONLY/O_RDONLY/O_RDWR) that was used when opening the device. This means that an audio/MIDI player can read the tags assigned by the whatever device/application is receiving the input (if it finds some use to this information). Equally well an audio/MIDI recorder may set the tags if necessary. This backstream usage may be useful with the label tags but probably not so useful with the song name tags.
The SNDCTL_AUDIOINFO and SNDCTL_MIDIINFO calls can be used to get the current label and song name tags for any audio or MIDI device. This feature is for example used by the ossxmix utility to find out the labels for certain mixer elements named as "@dsp#" (where # is the audio device number). If the device is found to be opened (pid != -1) the label field gives the current label (if no label was assigned then the label field will contain a copy of the cmd field).
You may have seen small (paper) labels attached to the channels of mixing consoles, audio/MIDI cables, effect processors, instruments and so on. They make it easier to manage the current setup.
The label tag string mechanism of OSS is a computer equivivalent of this. When the user attaches a label to a device/application (or an input/output of it) this information will be automatically visible to all devices/applications that are connected to them.
The idea is that the labels are only assigned by the user. If no label is given then OSS will automatically find a suitable label for it (or leave the label empty which tells the remote application to handle the situation as well as it can).
Labels can be at most 15 characters (plus a mandatory zero byte as a string terminator). However labels should be as short as possible (preferably less than 5 characters). Some applications don't have enough screen space to display longer labels than this. This is particularily important with labels automatically generated by the application.
A media player application can write the name of the song, movie or a media file to this tag. In this way applications or devices that receive the audio stream may use the song name for their purposes. For example a streaming media server can automatically obtain the name of the current song or program it's currently broadcasting.
The song name field can be at most 63 characters (plus the terminating zero byte). This is free format information. However if the application wants store both the artist/record name and the song name it should use a vertical bar ('|') character as the separator between these fields.