3 Oracle Multimedia ORD_AUDIO PL/SQL Package

Oracle Multimedia provides the ORD_AUDIO PL/SQL package. This package provides procedures to perform common operations such as importing and exporting audio data to and from operating system files, and extracting information from audio data.

This package adds Oracle Multimedia support to audio data stored in BLOBs and BFILEs.

The ORD_AUDIO package is defined in the ordarpsp.sql file. After installation, this file is available in the Oracle home directory at:

<ORACLE_HOME>/ord/im/admin (on Linux and UNIX)

<ORACLE_HOME>\ord\im\admin (on Windows)

The examples in these topics assume that the TAUD table and the AUDIODIR directory exist.

See the following topics for details about the procedures in the ORD_AUDIO PL/SQL package:

• ORD_AUDIO PL/SQL Package: getProperties( ) for BFILEs

• ORD_AUDIO PL/SQL Package: getProperties( ) (all attributes) for BFILEs

• ORD_AUDIO PL/SQL Package: getProperties( ) for BLOBs

• ORD_AUDIO PL/SQL Package: getProperties( ) (all attributes) for BLOBs

See Also:

• Procedures Common to All Oracle Multimedia PL/SQL Package APIs for information about exporting and importing audio data to and from operating system files

• Examples for Oracle Multimedia PL/SQL Packages for more information about the tables and directories used in the examples

3.1 ORD_AUDIO PL/SQL Package: getProperties( ) for BFILEs

Format

getProperties(audioBfile IN OUT NOCOPY BFILE, 
              attributes IN OUT NOCOPY CLOB);

Description

Reads the audio data stored in a BFILE to get the values of the media attributes for supported formats, and then stores them in the input CLOB. This procedure populates the CLOB with a set of format and application properties in XML form.

Parameters

audioBfile

The audio data represented as a BFILE.

attributes

The CLOB to hold the XML attribute information extracted by the getProperties( ) procedure. This CLOB is populated with a set of format and application properties of the audio BFILE data in XML form.

Usage Notes

None.

Pragmas

None.

Exceptions

None.

Examples

Get the property information for known audio attributes:

DECLARE
   aud_attrib CLOB;
   aud_data BFILE := BFILENAME('AUDIODIR','testaud.dat');
BEGIN
   DBMS_LOB.CREATETEMPORARY(aud_attrib, FALSE, DBMS_LOB.CALL);

   -- get properties from bfile
   ORDSYS.ORD_AUDIO.getProperties(aud_data, aud_attrib);

   -- print length of extracted properties
   DBMS_OUTPUT.PUT_LINE('Size of XML Annotations ' ||  
        TO_CHAR(DBMS_LOB.GETLENGTH(aud_attrib)));

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

3.2 ORD_AUDIO PL/SQL Package: getProperties( ) (all attributes) for BFILEs

Format

getProperties(audioBfile       IN OUT NOCOPY BFILE, 
              mimeType         OUT VARCHAR2, 
              format           OUT VARCHAR2, 
              encoding         OUT VARCHAR2, 
              numberOfChannels OUT INTEGER, 
              samplingRate     OUT INTEGER, 
              sampleSize       OUT INTEGER, 
              compressionType  OUT VARCHAR2, 
              audioDuration    OUT INTEGER);

Description

Reads the audio data stored in a BFILE to get the values of the media attributes for supported formats, and then returns them as explicit parameters. This procedure extracts the properties for these attributes of the audio data: duration, MIME type, compression type, format, encoding type, number of channels, sampling rate, and sample size.

Parameters

audioBfile

The audio data represented as a BFILE.

mimeType

The MIME type of the audio data.

format

The format of the audio data.

encoding

The encoding type of the audio data.

numberOfChannels

The number of channels in the audio data.

samplingRate

The sampling rate in samples per second at which the audio data was recorded.

sampleSize

The sample width or number of samples of audio in the data.

compressionType

The compression type of the audio data.

audioDuration

The total time required to play the audio data.

Usage Notes

If a property cannot be extracted from the media source, then the respective parameter is set to NULL.

Pragmas

None.

Exceptions

None.

Examples

Get the property information for known audio attributes:

DECLARE
   data BFILE:=BFILENAME('AUDIODIR','testaud.dat');
   mimeType VARCHAR2(80);
   format VARCHAR2(32):=NULL;
   encoding VARCHAR2(160);
   numberOfChannels NUMBER;
   samplingRate NUMBER;
   sampleSize NUMBER;
   compressionType VARCHAR2(160);
   audioDuration NUMBER;
BEGIN

   -- get properties from bfile
   ORDSYS.ORD_AUDIO.getProperties(data, mimeType, format, encoding,
        numberOfChannels, samplingRate, sampleSize, compressionType,
        audioDuration);

   -- print properties
   DBMS_OUTPUT.PUT_LINE('mimeType: ' || mimeType );
   DBMS_OUTPUT.PUT_LINE('format: ' || format );
   DBMS_OUTPUT.PUT_LINE('encoding: ' || encoding );
   DBMS_OUTPUT.PUT_LINE('numberOfChannels: ' || numberOfChannels ); 
   DBMS_OUTPUT.PUT_LINE('samplingRate: ' || samplingRate );
   DBMS_OUTPUT.PUT_LINE('sampleSize: ' || sampleSize );
   DBMS_OUTPUT.PUT_LINE('compressionType: ' || compressionType );
   DBMS_OUTPUT.PUT_LINE('audioDuration: ' || audioDuration );

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

3.3 ORD_AUDIO PL/SQL Package: getProperties( ) for BLOBs

Format

getProperties(audioBlob IN BLOB, attributes IN OUT NOCOPY CLOB);

Description

Reads the audio data stored in a BLOB to get the values of the media attributes for supported formats, and then stores them in the input CLOB. This procedure extracts the properties for these attributes of the audio data: duration, MIME type, compression type, format, encoding type, number of channels, sampling rate, and sample size. This procedure populates the CLOB with a set of format and application properties in XML form.

Parameters

audioBlob

The audio data represented as a BLOB.

attributes

The CLOB to hold the XML attribute information generated by the getProperties( ) procedure. This CLOB is populated with a set of format and application properties of the audio BLOB data in XML form.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDSourceExceptions.EMPTY_SOURCE

This exception is raised when the input audioBLOB parameter is NULL.

Examples

Get the property information for known audio attributes:

DECLARE
   aud_attrib CLOB;
   aud_data BLOB;
BEGIN
   SELECT aud, attributes INTO aud_data, aud_attrib 
        FROM taud WHERE N=1 FOR UPDATE;

   -- get properties from blob
   ORDSYS.ORD_AUDIO.getProperties(aud_data,aud_attrib);

   -- print length of extracted proterties
   DBMS_OUTPUT.PUT_LINE('Size of XML Annotations: ' ||
        TO_CHAR(DBMS_LOB.GETLENGTH(aud_attrib)));

   UPDATE taud SET attributes=aud_attrib WHERE N=1;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

3.4 ORD_AUDIO PL/SQL Package: getProperties( ) (all attributes) for BLOBs

Format

getProperties(audioBLOB        IN BLOB, 
              mimeType         OUT VARCHAR2, 
              format           OUT VARCHAR2, 
              encoding         OUT VARCHAR2, 
              numberOfChannels OUT INTEGER, 
              samplingRate     OUT INTEGER, 
              sampleSize       OUT INTEGER, 
              compressionType  OUT VARCHAR2, 
              audioDuration    OUT INTEGER);

Description

Reads the audio data stored in a BLOB to get the values of the media attributes for supported formats, and then returns them as explicit parameters. This procedure extracts the properties for these attributes of the audio data: duration, MIME type, compression type, format, encoding type, number of channels, sampling rate, and sample size.

Parameters

audioBLOB

The audio data represented as a BLOB.

mimeType

The MIME type of the audio data.

format

The format of the audio data.

encoding

The encoding type of the audio data.

numberOfChannels

The number of channels in the audio data.

samplingRate

The sampling rate in samples per second at which the audio data was recorded.

sampleSize

The sample width or number of samples of audio in the data.

compressionType

The compression type of the audio data.

audioDuration

The total time required to play the audio data.

Usage Notes

If a property cannot be extracted from the media source, then the respective parameter is set to NULL.

Pragmas

None.

Exceptions

ORDSourceExceptions.EMPTY_SOURCE

This exception is raised when the input audioBLOB parameter is NULL.

Examples

Get the property information for known audio attributes:

DECLARE
   aud_data BLOB;
   mimeType VARCHAR2(80);
   format VARCHAR2(32):=NULL;
   encoding VARCHAR2(160);
   numberOfChannels NUMBER;
   samplingRate NUMBER;
   sampleSize NUMBER;
   compressionType VARCHAR2(160);
   audioDuration NUMBER;
BEGIN
   SELECT aud, mimetype, format, encoding, numberofchannels, samplingrate,
          samplesize, compressiontype, audioduration 
       INTO aud_data, mimeType, format, encoding, numberOfChannels, 
            samplingRate, sampleSize, compressionType, audioDuration 
       FROM taud WHERE N=1 FOR UPDATE;

   -- get properties from blob
   ORDSYS.ORD_AUDIO.getProperties(aud_data, mimeType, format, encoding,
        numberOfChannels, samplingRate, sampleSize, compressionType, 
        audioDuration);

   -- print properties
   DBMS_OUTPUT.PUT_LINE('mimeType: ' || mimeType );
   DBMS_OUTPUT.PUT_LINE('format: ' || format );
   DBMS_OUTPUT.PUT_LINE('encoding: ' || encoding );
   DBMS_OUTPUT.PUT_LINE('numberOfChannels: ' || numberOfChannels );
   DBMS_OUTPUT.PUT_LINE('samplingRate: ' || samplingRate );
   DBMS_OUTPUT.PUT_LINE('sampleSize: ' || sampleSize );
   DBMS_OUTPUT.PUT_LINE('compressionType: ' || compressionType );
   DBMS_OUTPUT.PUT_LINE('audioDuration: ' || audioDuration );

   UPDATE taud SET 
         aud=aud_data, 
         mimetype=mimeType,
         format=format,
         encoding=encoding,
         numberofchannels=numberOfChannels,
         samplingrate=samplingRate,
         samplesize=sampleSize,
         compressiontype=compressionType,
         audioduration=audioDuration
       WHERE N=1;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/