==========
MMedia
==========

MMedia Framework 에 대한 필수 API 를 정의


---------
Media API
---------

미디어 관련된 기능들을 제공



미디어 촬영
--------------

.. js:function:: M.media.camera( setting )

	.. versionchanged:: 2.1.5.2
	
	:param Object setting: 사진 및 동영상 촬영을 위한 설정 정보
	:param String setting.path: 저장될 폴더명, 지정하지 않은 경우 기본값은 /media
	:param String setting.filename: 저장될 파일명, 확장자는 제외, 값을 지정하지 않은 경우 현재시간값으로 저장
	:param String setting.mediaType: 촬영 모드( PHOTO : 사진 / VIDEO: 영상 )
	:param String setting.direction: 촬영 방향 (FRONT / BACK : 안드로이드 적용 불가)
	:param Boolean setting.allowEdit: Edit 모드 사용 여부
	:param Boolean setting.saveAlbum: 앨범 저장 여부
	:param Boolean setting.overwrite: 덮어쓰기 여부, false 인 경우 파일명(중복수)로 적용됨
	:param Function setting.callback: 촬영 후 호출되는 콜백 함수

	.. js:function:: callback(status, result)

		:param String status: 실행 결과 ( SUCCESS: 성공 코드, FAIL: 실패 코드 )
		:param Object result: 실행 결과
		:param String result.path: 파일 경로 (도큐먼트로 부터의 경로, 로컬 웹서버를 통해 파일 접근 가능)
		:param int result.filesize: 파일 크기
		:param String result.filename: 파일명
		:param String result.saveDate: 저장 시간


	* 사진 및 동영상 촬영 화면으로 이동한다.


	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = path
		* source = path
		* name = filename
		* mode = mediaType
		* media = mediaType
		* type = mediaType
		* take = callback
		* ontake = callback

Example:

	* PHOTO 촬영

	.. code-block:: javascript

		M.media.camera({
			path: "/media",
			mediaType: "PHOTO",
			callback: function(status, result, option) {
				if (status == 'SUCCESS') {
					var photo_path = result.fullpath;
					var photo_name = result.name;
				}
			}
		});
		
	* PHOTO 촬영 후 앨범 저장

	.. code-block:: javascript

		M.media.camera({
			path: "/media",
			mediaType: "PHOTO",
			saveAlbum: true,
			callback: function(status, result, option) {
				if (status == 'SUCCESS') {
					var photo_path = result.fullpath;
					var photo_name = result.name;
				}
			}
		});


	* VIDEO 촬영

	.. code-block:: javascript

		M.media.camera({
			mediaType: "VIDEO",
			path: "/media",
			callback: function(status, result, option) {
				if (status == 'SUCCESS') {
					var photo_path = result.fullpath;
					var photo_name = result.name;
				}
			 }
		});



앨범으로 미디어 파일 저장
-------------------

.. js:function:: M.media.album( setting )

	.. versionchanged:: 2.1.5.2
	
	:param Object setting: 설정 정보
	:param String setting.path: 앨범으로 저장할 파일 명
	:param Function setting.callback: 결과 콜백 함수

	.. js:function:: callback(status, result)
		

		:param String status: 실행 결과 ( SUCCESS: 성공 코드, FAIL: 실패 코드 )
		:param Object result: 실행 결과
		:param String result.path: 파일 경로 (도큐먼트로 부터의 경로, 로컬 웹서버를 통해 파일 접근 가능)
		:param String result.name: 파일의 파일 이름

	* 미디어 폴더로 복사한다.

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = path
		* source = path
		* finish = callback
		* onfinish = callback

Example:

.. code-block:: javascript
	
	M.media.album({
		path: "/media/sample.jpg",
		onfinish: function(status, result, option) {
			if (status == 'SUCCESS') {
				var photo_path = result.path;
				var photo_name = result.name;
			}
		}
	});




미디어 정보
--------------

.. js:function:: M.media.info( setting )

	.. versionchanged:: 2.0.0
	
	:param Object setting: 미디어 정보를 가져오기 위한 설정 정보
	:param String setting.path: 정보를 가져오려는 디랙토리 경로
	:param String setting.mediaType: 미디어 타입 ( PHOTO: 사진, VIDEO: 동영상, AUDIO: 오디오 )
	:param Function setting.callback: 미디어 정보를 반환하는 콜백 함수

	.. js:function:: callback(status, result)
		

		:param String status: 실행 결과 ( SUCCESS: 성공 코드, FAIL: 실패 코드 )
		:param Object result: 실행 결과
		:param Array result.dirs: 디렉토리 정보
		:param Array result.files: 파일들 정보

	* 미디어 정보를 가져온다.

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = path
		* source = path
		* load = callback
		* onload = callback

Example:

	* 미디어 정보 (PHOTO)
	
	.. code-block:: javascript

		M.media.info({
			path: '/',
			mediaType: 'PHOTO',
			callback: function( status, result ) {
				console.log( status, result );
			}
		});
		

	* 미디어 정보 (VIDEO)
	
	.. code-block:: javascript

		M.media.info({
			path: '/',
			mediaType: 'VIDEO',
			callback: function( status, result ) {
				console.log( status, result );
			}
		});



공통 미디어 정보
--------------

.. js:function:: M.media.picker( setting )

	.. versionchanged:: 2.0.0
	
	:param Object setting: 공통 미디어 정보를 가져오기 위한 설정 정보
	:param String setting.mode: 선택 타입 ( SINGLE: 하나의 미디어 파일만 선택 가능, MULTI: 여러장 미디어 파일들을 선택 가능(media 타입이 PHOTO 일때만 지원함) )
	:param String setting.mediaType: 미디어 타입 ( PHOTO: 사진, VIDEO: 동영상, AUDIO: 오디오, ALL : 갤러리 )
	:param String setting.path: 미디어 경로
	:param int setting.maxCount: 최대 선택수 (기본값:0, 0인경우 제한없음)
	:param int setting.column: 미디어 선택 화면 컬럼 수
	:param Bool setting.detail: 상세 화면 모드
	:param Bool setting.zoom: 줌 모드
	:param Function setting.callback: 공통 미디어 정보를 반환하는 콜백 함수

	.. js:function:: callback(status, result)
		

		:param String status: 실행 결과 ( SUCCESS: 성공 코드, FAIL: 실패 코드 )
		:param Object result: 실행 결과
		:param String result.path: 파일 경로 (도큐먼트로 부터의 경로, 로컬 웹서버를 통해 파일 접근 가능)
		:param int result.size: 파일 크기
		:param String result.saveDate: 저장 시간
		:param String result.name: 파일의 파일 이름
		:param String result.orientation: 방향( 0, 90, 180, 270 )

	* 공통 미디어(사진, 동영상)를 가져오는 화면으로 이동한다. 

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = path
		* source = path
		* media = mediaType
		* type = mediaType
		* choose = mode
		* choice = mode
		* select = callback
		* onselect = callback


Example:

	
	* 사진 가져오기
	
	.. code-block:: javascript

		M.media.picker({
			mode: "SINGLE",
			media: "PHOTO",
			path: "/media",
			column: 3,
			callback: function( status, result ) {
				console.log( status + ", " + JSON.stringify(result) );
			}
		});

	* 동영상 가져오기

	.. code-block:: javascript
		
		M.media.picker({
			mode: "SINGLE",
			media: "VIDEO",
			path: "/media",
			callback: function( status, result ) {
				console.log( status + ", " + JSON.stringify(result) );
			}
		});


.. js:function:: M.media.library( setting )

	.. deprecated:: 2.1.1.1
	
	* M.media.picker 로 대체, 옵션은 동일


공통 미디어 삭제
---------------

.. js:function:: M.media.removelibrary( setting )

	.. versionchanged:: 2.0.0
	
	:param String setting.mediaType: 미디어 타입 ( PHOTO: 사진, VIDEO: 동영상, AUDIO: 오디오 )
	:param String setting.path: 미디어 경로
	:param Function setting.callback: 공통 미디어 정보를 반환하는 콜백 함수

	.. js:function:: callback(status, result)
		
		:param String status: 실행 결과 ( SUCCESS: 성공 코드, FAIL: 실패 코드 )
		:param Object result: 실행 결과
		

	* 공통 미디어(사진, 동영상)를 삭제한다. 

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = path
		* source = path
		* media = mediaType
		* type = mediaType
		* choose = mode
		* choice = mode
		* select = callback
		* onselect = callback


	Example:

	* Media 파일 삭제 (PHOTO)
	
	.. code-block:: javascript

		M.media.info({
			media: "PHOTO",
			path: "/media",
		}, function(status, result) {
			if ( status == 'SUCCESS' ) {
				console.log(result);

				var removeFiles = [];
				for ( var idx in result.files ) {
					var fileInfo = result.files[idx];
					removeFiles.push( fileInfo.path )
				}

				M.media.removeLibrary({
					files: removeFiles,
					media: "PHOTO"
				}, function(status, setting) {
					M.tool.log(status);
					alert(status);
				});
			}
			else {
				alert(status);
			}
		});
		
	
	* Media 파일 삭제 (VIDEO)
	
	.. code-block:: javascript
	
		M.media.info({
			media: "VIDEO",
			path: "/media",
		}, function(status, result) {
			if ( status == 'SUCCESS' ) {
				console.log(result);

				var removeFiles = [];
				for ( var idx in result.files ) {
					var fileInfo = result.files[idx];
					removeFiles.push( fileInfo.path )
				}

				M.media.removeLibrary({
					files: removeFiles,
					media: "VIDEO"
				}, function(status, setting) {
					M.tool.log(status);
					alert(status);
				});
			}
			else {
				alert(status);
			}
		});

동영상 플레이어
--------------

.. js:function:: M.media.play( setting ) 

	.. versionchanged:: 2.0.0
	
	:param Object setting: 영상 재생을 위한 설정 정보
	:param String setting.path: 재생할 영상 URL
	:param String setting.playType: URL 타입 ( NATIVE: 내장, 외장 메모리에 있는 URL 또는 Remote URL 처럼 직접 재생이 가능한경우, WEB: youtube URL처럼 직접 재생이 가능하지 않은 URL )

	* 영상을 재생하는 화면으로 이동한다.

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* url = path
		* alias = path
		* source = path
		* media = playType

Example:

	* 동영상 Play (WEB)
	
	.. code-block:: javascript

		M.media.play({
			path: "http://www.w3schools.com/html/mov_bbb.mp4",
			playType: "WEB"
		});
		

	* 동영상 Play (YOUTUBE)
	
	.. code-block:: javascript

		M.media.play({
			path: "https://youtu.be/RgKAFK5djSk",
			playType: "YOUTUBE"
		});


	* 동영상 촬영 후 Play
	
	.. code-block:: javascript

		M.media.camera({
			mode: "VIDEO",
			path: "/media",
		}, function(status, result, option) {
			if (status == 'SUCCESS') {
				var video_path = result.path;
				var video_name = result.name;
				var video_thumb = video_name.substr(0, video_name.lastIndexOf('.')) + ".png";

				M.media.play(video_path, 'NATIVE');
			}
		});



녹음
--------------

.. js:function:: M.media.record( setting ) 

	.. versionchanged:: 2.0.0
	
	:param Object setting: 파일 생성을 위한 설정 정보
	:param String setting.path: 녹취 파일이 저장될 경로 (폴더)
	:param String setting.filename: 녹취 파일 이름 (확장자 미포함), 없는경우 현재 시간으로 파일명을 만든다.
	:param Bool setting.overwrite: 덮어 쓰기 여부
	:param Function setting.callback: 녹취 결과 콜백 함수

	.. js:function:: callback(status, result)
		

		:param String status: 실행 결과 코드 ( SUCCESS: 성공 코드, FAIL: 실패 코드 )
		:param Object result: 실행 결과
		:param String result.path: 파일 경로 (도큐먼트로 부터의 경로, 로컬 웹서버를 통해 파일 접근 가능)
		:param int result.size: 파일 크기
		:param String result.saveDate: 저장 시간
		:param String result.name: 파일의 파일 이름

	* 녹취 기능 화면으로 이동한다.

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = path
		* source = path
		* name = filename
		* finish = callback
		* onfinish = callback


Example:


	* 녹음하기
	
	.. code-block:: javascript

		M.media.record({
			path: '/voiceList',
			filename: "sample",
			callback: function(status, result) {
				console.log( status + ", " + JSON.stringify(result) );

			}
		});


	* 녹음한 후 파일 재생하기
	
	.. code-block:: javascript

		M.media.record({
			path: '/voiceList',
			filename: "sample",
			callback: function(status, result) {
				M.media.info({
					path: '/voiceList',
					mediaType: 'AUDIO',
					callback: function( status, result ) {
						var voiceSource = result.files[0].fullpath; //녹음 리스트 중 첫번째 파일
						var audio = document.createElement("audio");
		               
						audio.autoplay = true;
						audio.load();
						audio.addEventListener("load", function() { 
							audio.play(); 
						}, true);
						audio.src = voiceSource;
					}
				});
			}
		});

미디어 정보 추출
--------------

.. js:function:: M.media.get( path ) 

	.. versionadd:: 2.1.5.1

	:param String path: 설정 옵션
	:returns: 미디어 정보
	:rtype: Object

	======================	==========	=============
	Key						Type		Description
	======================	==========	=============
	status					String		미디어 출력 상태 (SUCCESS or FAIL)
	error					String		오류 내용 (오류가 있을때만 키 존재)
	path					String		파일 경로 (도큐먼트로 부터의 경로, 로컬 웹서버를 통해 파일 접근 가능)
	alias					String		Scheme 경로 (doc:// 도큐먼트, app:// 번들리소스, media:// 미디어라이브러리, ext:// 외부저장장치로 부터의 경로)
	source					String		절대 경로 (Native 에서만 접근 가능)
	filename				String		파일명
	filesize				Int			파일용량
	duration				Float		비디오인경우 비디오 재생시간(초)
	orientation				Int			회전 상태 (0, 90, 180, 270)
	pixelWidth				Int			미디어 실제 너비
	pixelHeight				Int			미디어 실제 높이
	format					String		미디어 파일 포맷 (JPG, PNG, ""), 현재는 사진만 포맷값 추출 가능
	type					String		미디어 타입 (PHOTO, VIDEO, UNKNOWN)
	created					String		미디어 생성 시간 (DateFormat: yyyyMMddHHmmss)
	updated					String		미디어가 마지막으로 수정된 시간 (DateFormat: yyyyMMddHHmmss)
	======================	==========	=============

	* 경로는 항상 파일 경로만 적용 가능


Example:

	.. code-block:: javascript
		
		// 파일 다운로드 후 미디어 정보확인
		M.net.http.download({
			url: 'https://s3-ap-northeast-1.amazonaws.com/morpheus-storage/sample/sample.jpg',
			directory: '/download/',
			indicator: true,
			overwrite: true,
			progress: function(total, current) {},
			finish: function( statusCode, header, fileInfo, status, error ) {
				console.log( statusCode, header, fileInfo, status, error );
	
				if ( status !== "SUCCESS" ) {
					console.error( error );
					return;
				}
	
				var mediaInfo = M.media.get(fileInfo.path);
				M.tool.log( mediaInfo );
				alert( JSON.stringify(mediaInfo) );
			}
		});


.. js:function:: M.media.get( setting ) 

	.. versionadd:: 2.1.5.1
	
	:param Object setting: 설정 옵션
	:param String setting.path: 해당 미디어 경로

	** 결과는 위와 동일

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = path
		* source = path

Example:

	.. code-block:: javascript
		
		var mediaInfo = M.media.get({
			path: '/download/sample.jpg'
		});
		M.tool.log( mediaInfo );
		alert( JSON.stringify(mediaInfo) );



사진 최적화
--------------

.. js:function:: M.media.optimize( setting ) 

	.. versionadd:: 2.1.5.1
	
	:param Object setting: 설정 옵션
	:param String setting.source: 가져올 미디어 파일 경로
	:param String setting.destination: 출력할 미디어 파일 경로
	:param Bool setting.overwrite: 파일 덮어 쓰기 여부, false 가 기본값, 파일 존재시 파일명(숫자) 형태로 생성
	:param Object setting.dimension: 출력할 이미지 크기( width:Int, height:Int} ), 설정하지 않으면 실제 Pixel 크기 기준으로 생성
	:param String setting.format: 파일 포맷 (PNG, JPG), 기본값 PNG
	:param Float setting.quality: 파일 포맷이 JPG 인경우에만 품질 설정, 기본값은 1.0
	:param Function setting.callback: 파일 생성 후 호출되는 콜백 함수

	.. js:function:: callback(result)
		
		:param Object result: 생성 결과값
		:param String result.status: 결과 코드 {SUCCESS:성공 코드,FAIL:실패 코드,ERROR:실패 코드}
		:param String result.path: 파일 경로 (도큐먼트로 부터의 경로, 로컬 웹서버를 통해 파일 접근 가능)
		:param String result.alias: Scheme 경로 (doc:// 도큐먼트, app:// 번들리소스, media:// 미디어라이브러리, ext:// 외부저장장치로 부터의 경로)
		:param String result.source: 절대 경로 (Native 에서만 접근 가능)

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = source
		* source = source


Example:

	.. code-block:: javascript
	
		// 너비크기를 200으로, 파일 포맷은 기본값(PNG)로 변환하여 이미지 파일 생성
		M.media.optimize({
			'source': '/download/sample.jpg',
			'destination': '/download/sample.optimized.png',
			'dimension': { width:200 },
			'callback': function( result ) {
				if ( result.error ) {
					console.log( result.error );
					return;
				}
	
				console.log( M.media.get( result.path ) );
			}
		});
	
		// JPEG 의 해상도를 조정하여 이미지 용랑 조정
		M.media.optimize({
			'source': '/download/sample.jpg',
			'destination': '/download/sample.optimized.jpg',
			'overwrite': true,
			'quality': 0.5, // Only JPG
			'format': 'JPG',
			'callback': function( result ) {
				if ( result.error ) {
					console.log( result.error );
					return;
				}
	
				console.log( M.media.get( result.path ) );
			}
		});


사진 자르기
--------------

.. js:function:: M.media.crop( setting ) 

	.. versionadd:: 2.1.5.2
	
	:param Object setting: 설정 옵션
	:param String setting.source: 가져올 미디어 파일 경로
	:param String setting.destination: 출력할 미디어 파일 경로
	:param Bool setting.overwrite: 파일 덮어 쓰기 여부, false 가 기본값, 파일 존재시 파일명(숫자) 형태로 생성
	:param Object setting.dimension: 출력할 이미지 크기( width:Int, height:Int} ), 설정하지 않으면 실제 Pixel 크기 기준으로 생성, 값을 설정한 경우에는 해당값의 비율로 crop size 가 고정
	:param String setting.format: 파일 포맷 (PNG, JPG), 기본값 PNG
	:param Float setting.quality: 파일 포맷이 JPG 인경우에만 품질 설정, 기본값은 1.0
	:param String setting.title: 상단 네비게이션 타이틀 정의, 설정하지 않으면 Bundle 내 다국어로 적용
	:param String setting.doneButtonTitle: 취소 버튼 타이틀 정의, 설정하지 않으면 Bundle 내 다국어로 적용
	:param String setting.cancelButtonTitle: 완료 버튼 타이틀 정의, 설정하지 않으면 Bundle 내 다국어로 적용
	:param Function setting.callback: 파일 생성 후 호출되는 콜백 함수


	.. js:function:: callback(result)
		
		:param Object result: 생성 결과값
		:param String result.status: 결과 코드 {SUCCESS:성공 코드,FAIL:실패 코드,ERROR:실패 코드}
		:param String result.path: 파일 경로 (도큐먼트로 부터의 경로, 로컬 웹서버를 통해 파일 접근 가능)
		:param String result.alias: Scheme 경로 (doc:// 도큐먼트, app:// 번들리소스, media:// 미디어라이브러리, ext:// 외부저장장치로 부터의 경로)
		:param String result.source: 절대 경로 (Native 에서만 접근 가능)

	Surrogate Keys: 위 옵션키들과 같은 하위 버전 호환을 위한 대체 옵션 값들
		* alias = source
		* source = source


Example:

	.. code-block:: javascript
	
		// 너비크기를 200으로, 파일 포맷은 기본값(PNG)로 변환하여 이미지 파일 생성
		M.media.crop({
			'source': '/download/sample.jpg',
			'destination': '/download/sample.croped.jpg',
			'dimension': { width:200, height:200 },
			'optimize': 0.8, // Only JPG
			'format': 'JPG',
			'callback': function( result ) {
				if ( result.error ) {
					console.log( result.error );
					return;
				}
	
				console.log( M.media.get( result.path ) );
			}
		});