General aspects of Scald core

At a glance :
The scald core allows developers to unify their media asset thru bundles of entities ( Audio, Video, or one you will define ) using providers and manage them.

Scald Entities

Scald defines a bundle of entities per media type. Those types are registered by the media providers which are separated modules. This is done by this hook:
hook_entity_info : scald_entity_info()

  $return = array(
    'scald_atom' => array(
      'label' => t('Atoms'),
      'controller class' => 'ScaldAtomController',
      'base table' => 'scald_atoms',
      'uri callback' => 'scald_atom_uri',
      'fieldable' => TRUE,
      'entity keys' => array(
        'id' => 'sid',
        'bundle' => 'type',
        'label' => 'title',
      ),
      'bundle keys' => array(
        'bundle' => 'type'
      ),
      'bundles' => array(),
      'view modes' => array(),
      'view callback' => 'scald_render_multiple',
    )
  );

Then for each of the defined types of provider ( audio / video / ... ) we loop to define the informations :

  $types = scald_types();
  foreach ($types as $type => $info) {
    $return['scald_atom']['bundles'][$type] = array(
      'label' => $info->title,
      'admin' => array(
        'path' => 'admin/structure/scald/%scald_type',
        'bundle argument' => 3,
        'real path' => 'admin/structure/scald/' . $type,
        'access arguments' => array('administer content types')
      )
    );
  }

Scald CR(U)D

Scald Atom Shorthand ( SAS )

The SAS version of an atom is the way we use the filtering system to put atoms in textarea:
Any instance of Scald Atom Shorthand (SAS) will be replaced with a rendered Scald Atom. SAS can take any of the following formats: [scald=SID], [scald=SID:context], or [scald=SID:context context-options]. SID is the Scald ID, context is a context-slug, and context-options are additional formatting clues to give to the Context.
Without a Wysiwyg you can include Scald Atom Shorthand such as [scald=12]

Scald Actions and licences

Scald Actions are defined arbitrarily. The possible Actions that a given User can perform on a given Atom are determined by Action bitstrings. Each action has a position (arbitrarily-defined) in the bitstring. Due to PHP limitations, there is an upper bound of 31 Actions. The high bit in any actions Bitstring is the "admin bit" which, when set, means that the comparison is "OR", rather than "AND". Typically a user's Action bitstring (which is an OR-ing of all the Role Action bitstrings which the User is a part of) is AND-ed with the Atom's Action bitstring. However, if the Admin Bit is set, then a user's Action bitstring is *OR*-ed with the Atom's Action bitstring. Careful assignment of Action bitstrings to roles and roles to users should result in a fairly complete set of possibilities.

Scald Display contexts and rendering

Scald Core implements an input filter to allow for the inclusion of Scald Atoms in textareas in Drupal. When defining an input format, care should be taken to ensure that the rendered Scald Atoms (probably rendered in XHTML) are not subsequently processed into oblivion by other input filters. In other words, make sure that the Scald Atom Shorthand (SAS) Filter is *after* filters which strip tags.
The display context are defined thru the hook hook_scald_contexts. We define some in the library module like per example:

  return array(
    // This is the display we use when the atom is drag and dropped in the editor
    'sdl_editor_representation' => array(
      'title' => t('Editor Representation'),
      'description' => t('The Editor Rep'),
      'render_language' => 'XHTML',
      'parseable'       => TRUE,
      'formats'    => array(
        'image' => array('jpeg', 'png', 'passthrough'),
        'audio' => array('wav', 'ogg', 'mp3', 'passthrough'),
      ),
    ),

An example in a custom module when the image is to open in a lightbox when clicked.
(This should be part of a custom module):

/**
 * Implements hook_scald_contexts().
 */
function <MODULE>_scald_contexts() {
  $contexts = array();
  $contexts['my_lightbox_representation'] = array(
    'title'           => t('My Lightbox representation'),
    'description'     => t('My Lightbox representation'),
    'render_language' => 'XHTML',
    'parseable'       => TRUE,
    'formats'         => array('image' => array('jpg')),
    'type_format'         => array('image' => array('transcoder' => 'name-of-image-style')),
  );
  $context_config = scald_context_config_load('my_lightbox_representation');
  $context_config->transcoder['image']['*'] = 'name-of-image-style';
  scald_context_config_save($context_config);

  return $contexts;
}

/**
 * Render callback for the Atom with lightbox representation.
 */
function <MODULE>_scald_render($atom, $context, $options = array()) {
  if (strpos($context, 'my_lightbox_representation') === 0) {
    if (!empty($atom->rendered->thumbnail_transcoded_url)) {
      $path = $atom->rendered->thumbnail_transcoded_url;
    }
    else {
      $config = scald_context_config_load($context);
      // Find out which transcoder is in use, and checks if it's
      // one of the transcoder provided by Scald Image.
      $style_name = NULL;
      if ($transcoder = $config->transcoder[$atom->type]['*']) {
        // Image style support.
        if (preg_match('/^style-(.*)$/', $transcoder, $match)) {
          $style_name = $match[1];
        }
      }
      $preset = image_style_load($style_name);
      $path = image_style_url($preset['name'], $atom->thumbnail_source);
    }
    $node = menu_get_object();
    if ($node) {
      $title = $node->title;
    }
    else {
      $title = $atom->title;
    }

    return l(theme('image', array('path' => $path, 'alt' => $atom->title)), $atom->rendered->file_source_url,
      array(
        'attributes' => array('rel' => 'lightbox[' . $atom->provider . '][' . $title . ']'),
        'html' => TRUE,
      ));
  }
}

Loading Scald atoms in code

Loading atoms can be done with the scald_atom_load($sid) function, where $sid is the entity id of the Scald Atom Entity. The returned object will have all the attributes of the atom, including the title.
The scald_atom_load function will take permissions into account, and will not load the atom if the current user does not have access permissions to the atom.
The base_entity and base_id attributes usually contains the file object and the file id for file based providers. However generally providers can store anything in those attributes.

Scald hooks available to other modules

hook_scald_fetch
Used in scald_fetch(), we get the entity from the database then we have the provider put the default information thru this hook.

hook_scald_prerender
We initialize the $atom object in scald_prerender() then we pass it thru:

• Atom type prerendering
• Atom providers prerendering
• An optional transcoder prerendering
• A contex prerendering

via this hook.

hook_scald_render
hook_scald_rendered_to_sas_xhtml
hook_scald_rendered_to_sas_LANGUAGE
hook_scald_atom_providers
hook_scald_contexts
hook_scald_actions
hook_scald_register_atom
hook_scald_update_atom
hook_scald_atom_presave
hook_scald_atom_update
hook_scald_atom_insert
hook_scald_atom_delete
hook_scald_unregister_atom