[FFmpeg-soc] [soc] libavsequencer [PATCH 01/08] Music module public API header file.

[Vitor Sessak]

On 07/07/2010 10:46 PM, Sebastian Vater wrote:
> -- Best regards, :-) Basty/CDGS (-:
>
>
> module.h.patch

> /*
>  * AVSequencer music module management
>  * Copyright (c) 2010 Sebastian Vater <cdgs.basty at googlemail.com>
>  *
>  * This file is part of FFmpeg.
>  *
>  * FFmpeg is free software; you can redistribute it and/or
>  * modify it under the terms of the GNU Lesser General Public
>  * License as published by the Free Software Foundation; either
>  * version 2.1 of the License, or (at your option) any later version.
>  *
>  * FFmpeg is distributed in the hope that it will be useful,
>  * but WITHOUT ANY WARRANTY; without even the implied warranty of
>  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
>  * Lesser General Public License for more details.
>  *
>  * You should have received a copy of the GNU Lesser General Public
>  * License along with FFmpeg; if not, write to the Free Software
>  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>  */
>
> #ifndef AVSEQUENCER_MODULE_H
> #define AVSEQUENCER_MODULE_H
>
> #include "libavformat/avformat.h"
> #include "libavsequencer/avsequencer.h"
> #include "libavsequencer/instr.h"
> #include "libavsequencer/player.h"
>
> /**
>  * Sequencer module structure.
>  * New fields can be added to the end with minor version bumps.
>  * Removal, reordering and changes to existing fields require a major
>  * version bump.
>  */
> typedef struct AVSequencerModule {
>     /** Metadata information: Original module file name, module name,
>      *  module message, artist, genre, album, begin and finish date of
>      * composition and comment.  */
>     AVMetadata *metadata;

>     /** AVSequencerPlayerChannel pointer to virtual channel data.  */
>     AVSequencerPlayerChannel *channel_data;

Is there just a virtual channel data per file? And BTW, the "Player" 
part of the field bugs me. Does it really belongs to the BSS?

>     /** Array of pointers containing every sub-song for this
>        module.  */

"Array (of size songs) of pointers containing every sub-song for this 
module.", same for the others.

>     AVSequencerSong **song_list;
>
>     /** Array of pointers containing every instrument for this
>        module.  */
>     AVSequencerInstrument **instrument_list;
>
>     /** Array of pointers containing every evelope for this
>        module.  */
>     AVSequencerEnvelope **envelope_list;
>

>     /** Array of pointers containing every keyboard definitionb list

typo

>        for this module.  */
>     AVSequencerKeyboard **keyboard_list;
>
>     /** Array of pointers containing every arpeggio envelope
>        definition list for this module.  */
>     AVSequencerArpeggio **arpeggio_list;

>     /** Duration of the module, in AV_TIME_BASE fractional
>        seconds. This is the total sum of all sub-song durations
>        this module contains.  */
>     uint64_t duration;

Is this ever written in the files or is it calculated by the player? If 
the later, it does not belong to the BSS.

>     /** Number of sub-songs attached to this module.  */
>     uint16_t songs;

Cosmetics: I prefer, for readability, to move this closer to 
AVSequencerSong **song_list. Same for the following.

>     /** Number of instruments attached to this module.  */
>     uint16_t instruments;
>
>     /** Number of envelopes attached to this module.  */
>     uint16_t envelopes;
>
>     /** Number of keyboard definitions attached to this module.  */
>     uint16_t keyboards;
>
>     /** Number of arpeggio definitions attached to this module.  */
>     uint16_t arpeggios;

>     /** Maximum number of virtual channels, including NNA (New Note
>        Action) background channels to be allocated and processed by
>        the mixing engine (defaults to 64).  */
>     uint16_t channels;

Again, is it read from the file or calculated by the player?

> #define AVSEQ_MODULE_CHANNELS   64
>
>     /** Array of pointers containing every unknown data field where
>        the last element is indicated by a NULL pointer reference. The
>        first 64-bit of the unknown data contains an unique identifier
>        for this chunk and the second 64-bit data is actual unsigned
>        length of the following raw data. Some formats are chunk based
>        and can store information, which can't be handled by some
>        other, in case of a transition the unknown data is kept as is.
>        Some programs write editor settings for module in those chunks,
>        which then won't get lost in that case.  */
>     uint8_t **unknown_data;
> } AVSequencerModule;
>
> /**
>  * Opens and registers module to the AVSequencer.
>  *
>  * @param avctx the AVSequencerContext to store the opened module into
>  * @param module the AVSequencerModule which has been opened to be registered
>  * @return >= 0 on success, a negative error code otherwise
>  *
>  * @note This is part of the new sequencer API which is still under construction.
>  *       Thus do not use this yet. It may change at any time, do not expect
>  *       ABI compatibility yet!
>  */
> int avseq_module_open(AVSequencerContext *avctx, AVSequencerModule *module);

Hmm, I think I don't really understand what this function do. Suppose 
you want to write a very short test program to play a MOD file using the 
libraries. Roughly, what functions it will call, in which order and with 
which parameters?

-Vitor