overte-JulianGro/script-archive/audioExamples/acAudioSearching/ACAudioSearchAndInject.js

"use strict";
/*jslint nomen: true, plusplus: true, vars: true*/
/*global AvatarList, Entities, EntityViewer, Script, SoundCache, Audio, print, randFloat*/
//
//  ACAudioSearchAndInject.js
//  audio
//
//  Created by Eric Levin and Howard Stearns 2/1/2016
//  Copyright 2016 High Fidelity, Inc.
//
//  Keeps track of all sounds within QUERY_RADIUS of an avatar, where a "sound" is specified in entity userData.
//  Inject as many as practical into the audio mixer.
//  See acAudioSearchAndCompatibilityEntitySpawner.js.
//
//  This implementation takes some precautions to scale well:
//  - It doesn't hastle the entity server because it issues at most one octree query every UPDATE_TIME period, regardless of the number of avatars.
//  - It does not load itself because it only gathers entities once every UPDATE_TIME period, and only
//    checks entity properties for those small number of entities that are currently playing (plus a RECHECK_TIME period examination of all entities).
//  This implementation tries to use all the available injectors.
//
//  Distributed under the Apache License, Version 2.0.
//  See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html

var MSEC_PER_SEC = 1000;
var SOUND_DATA_KEY = "io.highfidelity.soundKey"; // Sound data is specified in userData under this key.
var old_sound_data_key = "soundKey"; // For backwards compatibility.
var QUERY_RADIUS = 50; // meters
var UPDATE_TIME = 100; // ms. We'll update just one thing on this period.
var EXPIRATION_TIME = 5 * MSEC_PER_SEC; // ms. Remove sounds that have been out of range for this time.
var RECHECK_TIME = 10 * MSEC_PER_SEC; // ms. Check for new userData properties this often when not currently playing.
// (By not checking most of the time when not playing, we can efficiently go through all entities without getEntityProperties.)
var UPDATES_PER_STATS_LOG = RECHECK_TIME / UPDATE_TIME; // (It's nice to smooth out the results by straddling a recheck.)

var DEFAULT_SOUND_DATA = {
    volume: 0.5, // userData cannot specify zero volume with our current method of defaulting.
    loop: false, // Default must be false with our current method of defaulting, else there's no way to get a false value.
    playbackGap: MSEC_PER_SEC, // in ms
    playbackGapRange: 0 // in ms
};

Script.include("../../libraries/utils.js");
Agent.isAvatar = true; // This puts a robot at 0,0,0, but is currently necessary in order to use AvatarList.
function ignore() {}
function debug() { // Display the arguments not just [Object object].
    //print.apply(null, [].map.call(arguments, JSON.stringify));
}

EntityViewer.setCenterRadius(QUERY_RADIUS);

// ENTITY DATA CACHE
// 
var entityCache = {}; // A dictionary of unexpired EntityData objects.
var examinationCount = 0;
function EntityDatum(entityIdentifier) { // Just the data of an entity that we need to know about.
    // This data is only use for our sound injection. There is no need to store such info in the replicated entity on everyone's computer.
    var that = this;
    that.lastUserDataUpdate = 0; // new entity is in need of rechecking user data
    // State Transitions:
    // no data => no data | sound data | expired
    //   expired => stop => remove
    //   sound data => downloading
    //     downloading => downloading | waiting
    //       waiting => playing | waiting (if too many already playing)
    //         playing => update position etc | no data
    that.stop = function stop() {
        if (!that.sound) {
            return;
        }
        print("stopping sound", entityIdentifier, that.url);
        delete that.sound;
        delete that.url;
        if (!that.injector) {
            return;
        }
        that.injector.stop();
        delete that.injector;
    };
    this.update = function stateTransitions(expirationCutoff, userDataCutoff, now) {
        if (that.timestamp < expirationCutoff) {                             // EXPIRED => STOP => REMOVE
            that.stop(); // Alternatively, we could fade out and then stop...
            delete entityCache[entityIdentifier];
            return;
        }
        var properties, soundData; // Latest data, pulled from local octree.
        // getEntityProperties locks the tree, which competes with the asynchronous processing of queryOctree results.
        // Most entity updates are fast and only a very few do getEntityProperties.
        function ensureSoundData() { // We only getEntityProperities when we need to.
            if (properties) {
                return;
            }
            properties = Entities.getEntityProperties(entityIdentifier, ['userData', 'position']);
            examinationCount++; // Collect statistics on how many getEntityProperties we do.
            debug("updating", that, properties);
            try {
                var userData = properties.userData && JSON.parse(properties.userData);
                soundData = userData && (userData[SOUND_DATA_KEY] || userData[old_sound_data_key]); // Don't store soundData yet. Let state changes compare.
                that.lastUserDataUpdate = now;                    // But do update these ...
                that.url = soundData && soundData.url;
                that.playAfter = that.url && now;
            } catch (err) {
                print(err, properties.userData);
            }
        }
        // Stumbling on big new pile of entities will do a lot of getEntityProperties. Once.
        if (that.lastUserDataUpdate < userDataCutoff) {                      // NO DATA => SOUND DATA
            ensureSoundData();
        }
        if (!that.url) {                                                     // NO DATA => NO DATA
            return that.stop();
        }
        if (!that.sound) {                                                   // SOUND DATA => DOWNLOADING
            that.sound = SoundCache.getSound(soundData.url); // SoundCache can manage duplicates better than we can.
        }
        if (!that.sound.downloaded) {                                        // DOWNLOADING => DOWNLOADING
            return;
        }
        if (that.playAfter > now) {                                          // DOWNLOADING | WAITING => WAITING
            return;
        }
        ensureSoundData(); // We'll try to play/setOptions and will need position, so we might as well get soundData, too.
        if (soundData.url !== that.url) {                                    // WAITING => NO DATA (update next time around)
            return that.stop();
        }
        var options = {
            position: properties.position,
            loop: soundData.loop || DEFAULT_SOUND_DATA.loop,
            volume: soundData.volume || DEFAULT_SOUND_DATA.volume
        };
        function repeat() {
            return !options.loop && (soundData.playbackGap >= 0);
        }
        function randomizedNextPlay() { // time of next play or recheck, randomized to distribute the work
            var range = soundData.playbackGapRange || DEFAULT_SOUND_DATA.playbackGapRange,
                base = repeat() ? ((that.sound.duration * MSEC_PER_SEC) + (soundData.playbackGap || DEFAULT_SOUND_DATA.playbackGap)) : RECHECK_TIME;
            return now + base + randFloat(-Math.min(base, range), range);
        }
        if (!that.injector) {                                                // WAITING => PLAYING | WAITING
            debug("starting", that, options);
            that.injector = Audio.playSound(that.sound, options); // Might be null if at at injector limit. Will try again later.
            if (that.injector) {
                print("started", entityIdentifier, that.url);
            } else { // Don't hammer ensureSoundData or injector manager.
                that.playAfter = randomizedNextPlay();
            }
            return;
        }
        that.injector.setOptions(options);                                   // PLAYING => UPDATE POSITION ETC
        if (!that.injector.isPlaying) { // Subtle: a looping sound will not check playbackGap.
            if (repeat()) {                                                  // WAITING => PLAYING
                // Setup next play just once, now. Changes won't be looked at while we wait.
                that.playAfter = randomizedNextPlay();
                // Subtle: if the restart fails b/c we're at injector limit, we won't try again until next playAfter.
                that.injector.restart();
            } else {                                                        // PLAYING => NO DATA
                that.playAfter = Infinity; // was one-shot and we're finished
            }
        }
    };
}
function internEntityDatum(entityIdentifier, timestamp, avatarPosition, avatar) {
    ignore(avatarPosition, avatar); // We could use avatars and/or avatarPositions to prioritize which ones to play.
    var entitySound = entityCache[entityIdentifier];
    if (!entitySound) {
        entitySound = entityCache[entityIdentifier] = new EntityDatum(entityIdentifier);
    }
    entitySound.timestamp = timestamp; // Might be updated for multiple avatars. That's fine.
}
var nUpdates = UPDATES_PER_STATS_LOG, lastStats = Date.now();
function updateAllEntityData() { // A fast update of all entities we know about. A few make sounds.
    var now = Date.now(),
        expirationCutoff = now - EXPIRATION_TIME,
        userDataRecheckCutoff = now - RECHECK_TIME;
    Object.keys(entityCache).forEach(function (entityIdentifier) {
        entityCache[entityIdentifier].update(expirationCutoff, userDataRecheckCutoff, now);
    });
    if (nUpdates-- <= 0) { // Report statistics.
        // For example, with:
        //  injector-limit = 40 (in C++ code)
        //  N_SOUNDS = 1000    (from userData in, e.g., acAudioSearchCompatibleEntitySpawner.js)
        //  replay-period = 3 + 20 = 23 (seconds, ditto)
        //  stats-period = UPDATES_PER_STATS_LOG * UPDATE_TIME / MSEC_PER_SEC = 10 seconds
        // The log should show between each stats report:
        //  "start" lines ~= injector-limit * P(finish) = injector-limit * stats-period/replay-period = 17 ?
        //  total attempts at starting ("start" lines + "could not thread" lines) ~= N_SOUNDS = 1000 ?
        //  entities > N_SOUNDS * (1+ N_SILENT_ENTITIES_PER_SOUND) = 11000 + whatever was in the scene before running spawner
        //  sounds = N_SOUNDS = 1000
        //  getEntityPropertiesPerUpdate ~= playing + failed-starts/UPDATES_PER_STATS_LOG + other-rechecks-each-update
        //     = injector-limit + (total attempts - "start" lines)/UPDATES_PER_STATS__LOG
        //       + (entities - playing - failed-starts/UPDATES_PER_STATS_LOG) * P(recheck-in-update)
        //                     where failed-starts/UPDATES_PER_STATS_LOG = (1000-17)/100 = 10
        //     = 40 + 10 + (11000 - 40 - 10)*UPDATE_TIME/RECHECK_TIME
        //     = 40 + 10 + 10950*0.01 = 159   (mostly proportional to enties/RECHECK_TIME)
        //  millisecondsPerUpdate ~= UPDATE_TIME = 100 (+ some timer machinery time)
        //  this assignment client activity monitor < 100% cpu
        var stats = {
            entities: 0,
            sounds: 0,
            playing: 0,
            getEntityPropertiesPerUpdate: examinationCount / UPDATES_PER_STATS_LOG,
            millisecondsPerUpdate: (now - lastStats) / UPDATES_PER_STATS_LOG
        };
        nUpdates = UPDATES_PER_STATS_LOG;
        lastStats = now;
        examinationCount = 0;
        Object.keys(entityCache).forEach(function (entityIdentifier) {
            var datum = entityCache[entityIdentifier];
            stats.entities++;
            if (datum.url) {
                stats.sounds++;
                if (datum.injector && datum.injector.isPlaying) {
                    stats.playing++;
                }
            }
        });
        print(JSON.stringify(stats));
    }
}

// Update the set of which EntityData we know about.
//
function updateEntiesForAvatar(avatarIdentifier) { // Just one piece of update work.
    // This does at most:
    //   one queryOctree request of the entity server, and
    //   one findEntities geometry query of our own octree, and
    //   a quick internEntityDatum of each of what may be a large number of entityIdentifiers.
    // The idea is that this is a nice bounded piece of work that should not be done too frequently.
    // However, it means that we won't learn about new entities until, on average (nAvatars * UPDATE_TIME) + query round trip.
    var avatar = AvatarList.getAvatar(avatarIdentifier), avatarPosition = avatar && avatar.position;
    if (!avatarPosition) { // No longer here.
        return;
    }
    var timestamp = Date.now();
    EntityViewer.setPosition(avatarPosition);
    EntityViewer.queryOctree(); // Requests an update, but there's no telling when we'll actually see different results.
    var entities = Entities.findEntities(avatarPosition, QUERY_RADIUS);
    debug("found", entities.length, "entities near", avatar.name || "unknown", "at", avatarPosition);
    entities.forEach(function (entityIdentifier) {
        internEntityDatum(entityIdentifier, timestamp, avatarPosition, avatar);
    });
}

// Slowly update the set of data we have to work with.
//
var workQueue = [];
function updateWorkQueueForAvatarsPresent() { // when nothing else to do, fill queue with individual avatar updates
    workQueue = AvatarList.getAvatarIdentifiers().map(function (avatarIdentifier) {
        return function () {
            updateEntiesForAvatar(avatarIdentifier);
        };
    });
}
Script.setInterval(function () {
    // There might be thousands of EntityData known to us, but only a few will require any work to update.
    updateAllEntityData(); // i.e., this better be pretty fast.
    // Each interval, we do no more than one updateEntitiesforAvatar.
    if (!workQueue.length) {
        workQueue = [updateWorkQueueForAvatarsPresent];
    }
    workQueue.pop()(); // There's always one
}, UPDATE_TIME);